Skip to content

fix(ios): drain autoreleased Metal objects on the offscreen worker - #19

Merged
riteshshukla04 merged 7 commits into
margelo:mainfrom
mickeypause:fix/ios-offscreen-autorelease-pool
Nov 4, 2026
Merged

riteshshukla04 merged 7 commits into
margelo:mainfrom
mickeypause:fix/ios-offscreen-autorelease-pool

Conversation

@mickeypause

@mickeypause mickeypause commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Idea behind this PR

I encountered this issue while porting my drawing app from Skia to tgfx. The app lets users draw on a canvas, but repeated offscreen rendering caused a massive increase in RAM usage, even when the rendered content wasn't visible on screen.

The offscreen worker wasn't draining autoreleased temporary objects between render passes. This PR adds an autorelease pool around each Apple offscreen worker pass so those objects are released correctly.


<------- Anything below here was generated by AI. ------->

Problem and fix

The process-wide offscreen worker is a detached C++ thread. Repeated filtered renders can accumulate autoreleased Apple objects despite callers disposing input images and snapshots.

On Apple, run each worker pass inside @autoreleasepool, including acquisition and destruction of its temporary strong surface reference. Android keeps the existing direct C++ call. This addresses temporary-object lifetime, not visibility culling.

Scope

Four files, +89/−0 lines:

  • Dispatch Apple worker passes through a new Objective-C++ helper, included by the existing CocoaPods glob.
  • Link the helper/Foundation and enable Objective-C++20 for the Apple native-test target.
  • Add the 450-render workload to the existing offscreen.harness.tsx, with upload, moving-rectangle and blur-boundary pixel assertions. It runs with the normal suite; no separate Harness file, custom flag or default name filter.

No public API, wire format, engine pin, Swift, Android implementation, podspec, contribution-guide or host-sampler changes.

Reproduce and validate

Configure the existing ios-sim runner for your simulator and install a matching Debug example build:

cd apps/example
bun run harness src/offscreen.harness.tsx --harnessRunner=ios-sim --testNamePattern='offscreen leak soak'

This command checks pixels, not memory. The external, PID-aware RSS checker and its regression tests live on a separate validation commit; see its reproduction commands. On this branch, pass --test src/offscreen.harness.tsx; that runs the regular offscreen checks together with the soak.

Two fresh-process iOS 27 Simulator Debug pairs completed all 450 renders:

Pair Base settled RSS growth Fixed settled RSS growth
November 2 +54.5 MiB — fails +2.0 MiB — passes
November 3 +41.5 MiB — fails +0.9 MiB — passes

The external gate compares settled medians against 30 MiB. Both workers pass pixel assertions; bypassing blur fails the boundary assertion and cannot produce a passing memory verdict. RSS is process accounting, not GPU-only memory.

Additional recorded coverage:

  • 404 core + 2 camera unit tests, core/camera typecheck and lint, code generation/package inclusion, and iOS/Android native builds pass. Core unit tests, lint and typecheck were rerun before opening this PR.
  • iPhone 15 Pro, iOS 27.0, arm64 Release: both workers pass the 450-render pixel workload and valid hit-test/PNG save/reload/disposal checks. Instruments settled physical-footprint growth is about +2.4 MiB on each. This short hardware run does not reproduce the simulator leak or establish hardware RAM savings.
  • Two Android arm64 Vulkan/SwiftShader emulator soaks pass; the Apple code is not compiled on Android. No physical Android GPU claim is made.
  • Full pinned Harness repeats have the same 191 passed / 8 failed on base and fixed. Native SceneTest passes its assertions but aborts during shaderc/glslang shutdown on both workers; SnapshotTest and AllocBench exit 0. Existing example/benchmark tooling failures and missing approved image baselines remain. The whole repository is not green.

Detailed results, controls and limitations are in our fork review PR. Device startup/signing adjustments used during validation were local and restored.

The branch is now rebased onto upstream bcf2223 (including merged PR #18), with rebased fix revision 3313b99. The two configuration conflicts were resolved by preserving upstream's runner settings and adding offscreenLeakSoak to its existing Jest exclusion list. The native fix merged without conflicts. After rebase, 406 core tests, core lint and typecheck pass. Earlier device and memory results above target d8b5c58, based on alpha.12 (adee18e); native/device builds and the memory regression have not yet been rerun against the updated engine.

The test consolidation is a single follow-up commit, 642d0a5, atop the rebased fix. Its tree is identical to the locally validated consolidation: 406 core tests pass; core lint/typecheck and example lint pass; the example's eight type errors match the original committed sources. Jest CLI configuration confirms no default name filter, with standard --testNamePattern available for a focused run. Native/device and memory checks have not been rerun after this move.

App demonstration

Before/after MP4 and capture details document the original investigation in a separate drawing app on tgfx alpha.8. The clip starts with memory already accumulated and reports UI callback cadence, not hardware presentation FPS. It is supporting demonstration, separate from the alpha.12 library regression above.

@vercel

vercel Bot commented Nov 3, 2026

Copy link
Copy Markdown

@mickeypause is attempting to deploy a commit to the Margelo Team on Vercel.

A member of the Team first needs to authorize it.

@riteshshukla04

Copy link
Copy Markdown
Member

Can you rebase your PR with main

Bound Metal temporaries to each worker drain, including final surface cleanup. Keep the Android C++ path unchanged.

450 filtered renders: RSS growth +51.6 MiB before, -3.7 MiB after (30 MiB gate; Debug iOS Simulator).
Discard earlier-process RSS samples after Harness restarts the app.
Assert blur blends an interior boundary; reject a zero-blur control.

Add regression checks for process changes and insufficient samples.
Restore contributor docs, runner configuration, and Android leak tooling.
Preserve iOS measurement tools on validation/ios-offscreen-memory.
Keep the offscreen workload and its combined Jest exclusion list.
@mickeypause

Copy link
Copy Markdown
Contributor Author

Can you rebase your PR with main

Done

@riteshshukla04

Copy link
Copy Markdown
Member

Can you also delete the harness file and adjust it in existing one. Lets not add new files for everything

@mickeypause

Copy link
Copy Markdown
Contributor Author

Can you also delete the harness file and adjust it in existing one. Lets not add new files for everything

Updated

@riteshshukla04

Copy link
Copy Markdown
Member

I found same issue with images. So I fixed it here

Hold the pool in OffscreenContext instead of around the worker loop.
renderToImage, encode and save take the offscreen device on Nitro's
promise threads, which never drain a pool either. Every offscreen GPU
call already runs inside an OffscreenContext, so one RAII member covers
the worker, those calls and surface teardown.

450 iterations on the iOS 27 simulator:
- offscreen leak soak: +2.5 MiB
- renderToImage: +2.6 MiB (was +83.5 MiB)
- encode('png'): flat (was +50.9 MiB)
@riteshshukla04
riteshshukla04 merged commit cdcb4e5 into margelo:main Nov 4, 2026
4 of 6 checks passed
@riteshshukla04

Copy link
Copy Markdown
Member

Thanks for fixing this :)

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