android: Rework the JNI layer (Activity lifetime, exceptions, UI thread, class cache)

[Bombatomica64]

Refactor of how gpui-mobile talks to Java on Android, from an audit of src/android/jni.rs, the core files and all 30 packages/*/android.rs. Every commit stands alone, builds, and adds no clippy warnings over main. Each is meant to become one small upstream PR later.

Commits

1. Correct the JNI helper docs. with_env claimed it detaches the thread on return. jni 0.22 attaches permanently, and an exception still pending at the end replaces the closure's result. obtain_env is deprecated, and the unsafe blocks get SAFETY comments.
2. Clear and describe Java exceptions in the core JNI calls.
   • New JniResultExt::or_clear(env) clears the pending exception and returns its toString(), so errors read java.lang.SecurityException: … instead of JavaException.
   • get_string now checks that the object is a java.lang.String. Before, it read any object as one.
3. Hand out the host Activity as a local reference. This fixes the most serious problem the audit found:
   • The old code wrapped a raw global ref after releasing the lock and kept only one previous Activity. Two recreations during one call could delete a reference that call was still using.
   • A finished Activity stayed "current" (used and leaked) until the next onCreate.
   • Now set_host_activity registers Activities in a list. activity(env) returns a local ref, taken under the lock, to the newest Activity that is neither finishing nor destroyed, and drops the others.
   • New application_context(). The accessibility bridge goes through activity().
4. Cache the app class loader and the classes found through it. find_app_class cost three extra JNI calls on each of about 110 call sites and needed an Activity. The loader now comes from the application context, once, and each class found is kept as a global ref.
5. Run Window and View calls on the UI thread.
   • set_system_chrome and update_ime_position ran on the render thread; the code itself noted a possible deadlock.
   • New run_on_ui_thread posts to the UI thread's looper through an eventfd (NDK only, no Java). It is registered in set_host_activity.
   • The android-activity path has no way to reach the UI thread without Java, so calls run in place there, as before.
6. Clear and describe Java exceptions in the platform packages. The same or_clear rule, applied mechanically across the packages. Discarded results are logged at debug level, and swallowed errors clear the exception before falling back.
7. Use the application context where packages only need a Context (getSystemService, getPackageManager, …).
8. Call ClipboardManager, the launch Intent and the Play Store from Rust.
   • The clipboard, deeplink and in-app-review packages called Java helpers that only forwarded to framework APIs. A host that hadn't copied them got a loadClass error.
   • Same behaviour through JNI now, and GpuiClipboard.java, GpuiDeepLink.java and GpuiInAppReview.java are removed from the example.

Not in scope: behaviour bugs in individual packages, such as unbounded waits in the pickers, auth and permissions, dead webview controls, and content:// URIs reported as paths. They're listed in the audit for later.

Testing

• cargo fmt --all -- --check and cargo clippy --target aarch64-linux-android --lib --all-features after each commit, with the same warning list as main.
• On a OnePlus CPH2581 (Android 16), through the lab app (Test: gpui-mobile jni-refactor Gpui-android#24):
  • Three Activity recreations in a row in one process (am start -f NEW_TASK|CLEAR_TASK): no JNI errors.
  • After those recreations, share and the keyboard both worked, which is what exercises the new Activity registry.
  • Typing worked, and the viewport resized for the keyboard.
  • Clipboard copy and read worked, through the new Rust path.
  • Night mode switched at runtime, and emoji rendered.
• Not tested: TalkBack, and the system bar colours (the lab may not set them). There's no real rotation because the lab is portrait-only.

🤖 Generated with Claude Code

[Bombatomica64]

Review of the branch (core files read in full, packages swept, clippy clean on aarch64-linux-android). The design holds up: the Activity registry, or_clear, the class cache and the UI-thread dispatcher match what jni 0.22.4 and ndk 0.9 actually do. No blocking bug. Things I'd change before splitting this for upstream:

Fix

1. src/packages/in_app_review/android.rs:60 — view(market)? short-circuits on any error before startActivity (Uri.parse, Intent ctor, no Activity), so the https://play.google.com fallback is never tried. The deleted Java caught everything and fell through. view(market).unwrap_or(false) || view(https)?.
2. Same file, is_available — every exception now reads as "not installed"; Java only caught NameNotFoundException. A missing <queries> entry on API 30+ becomes silent. At least log the cleared description.
3. jni.rs:585 activity_as_ptr() has no callers left except its own test. It's the only remaining way to hold a raw global the registry may delete. Remove or #[deprecated] it rather than documenting "don't keep".

Description overclaims the sweep

• ~24 bare env.exception_clear() sites remain (battery, connectivity, maps_launcher, network_info, package_info, sensors, share, url_launcher, vibration). Correct, but they lose the exception text or_clear exists for. sensors/android.rs:66 is now dead code (already cleared on line 64).
• battery/android.rs:83 and shared_preferences/android.rs:206 still use activity(env) for Context-only calls.
• vibration/android.rs:12 leaves a find_class failure pending into the fallback vibrate(J) call. Dead with minSdk 26, but contradicts the rule this PR sets.

Pre-existing, touched here
LAST_CHROME_STYLE is only reset on the android-activity TerminateWindow path (jni.rs:1093). On the host path a recreated Activity never gets the chrome re-applied. A None reset in set_host_activity would do.

Size / safety / perf

• Commits 5, 6 and 8 are two thirds of the diff. Commit 5 is mostly re-indentation; a small run_on_ui_thread variant that owns the (|| -> Result)() + log::warn! boilerplate would halve it. Commit 8 splits naturally per package. 1–4 and 7 are already upstream-sized.
• activity() on the host path now does isFinishing + isDestroyed per registered Activity, under the mutex, on every call — that's the hot path for every package and gives back some of what the class cache saved. Prune in set_host_activity (and an onDestroy hook) instead, or skip the check when the single registered Activity passed last time.
• run_on_ui_thread queues into an unbounded Vec; update_ime_position is frequent. If a host's looper stops being polled, tasks pile up silently. Coalescing the IME task to latest-wins, or a bound, is cheap insurance.

Verified: jni 0.22.4 attach_current_thread attaches permanently and turns a pending exception into CaughtJavaException (commit 1's doc is right); ALooper_forThread works on the Java main thread; clipboard and deeplink ports are behaviourally equivalent to the deleted Java; all new JNI signatures and static/instance calls match the framework; nothing under src/packages keeps the local Activity ref past its frame. Not run on a device.

[Bombatomica64]

Reviewed head 9b25c73. One confirmed regression:

• P2 — shared_preferences/android.rs:L247: Java write failures are cleared and logged, then reported as Ok(()). Previously, with_env propagated the pending exception. Use .or_clear(env)? for commit and the editor mutations. I reproduced this with the actual base/head preference implementations and a Java stub whose commit() throws: base returns Err, head returns Ok.

The PR could be smaller and safer to review. It mixes 1,062 additions and 1,032 deletions across 34 files. Split the existing commits into focused PRs for exception handling, Activity lifetime, class caching, UI dispatch, and Java helper removal. The helper removal can ship independently; it adds substantial handwritten JNI unrelated to fixing Activity references.

Two further recommendations, separate from the confirmed regression:

• Safety — jni.rs:L585: activity_as_ptr() still exposes a global reference after releasing its lock. Another thread can prune it before use; “must not be kept” cannot prevent that race. Deprecate this accessor and migrate consumers to activity(env).
• Performance — jni.rs:L698: The UI queue drains every pending task without a limit. Coalesce pending IME position updates so a busy UI thread processes the latest position instead of replaying obsolete ones. This is a code-level recommendation, not a measured slowdown.

Validation covered source review and the JVM reproduction. I did not run an Android build or device tests; TalkBack and Activity transitions deserve targeted verification before merging the lifecycle changes.

[Bombatomica64]

Thanks to both reviews. I pushed four commits on top (3fc49ca..f77414c).

Exception handling: the sweep is now complete. The first pass only rewrote one pattern.

• Every call into Java in src/android/*.rs and src/packages/*/android.rs now goes through or_clear. A new or_catch(env, class) makes expected exceptions explicit:
  • ActivityNotFoundException for startActivity in url_launcher, maps_launcher and in_app_review
  • NameNotFoundException in in_app_review is_available
  • NoSuchMethodError for the pre-API-30 system chrome path
  • NoClassDefFoundError for VibrationEffect
• Any other exception is now an error instead of a quiet false or default.
• grep exception_clear|exception_check finds only the three calls inside take_exception/or_catch.
• Functions that return a plain value log the error before falling back to their default.

Confirmed regression, fixed: shared_preferences writes and commit() return their error again, and commit() returning false is an error.

Review points:

• in_app_review: the market:// attempt falls through to the web page on any failure, and is_available catches only NameNotFoundException. ✔
• activity_as_ptr() is #[deprecated]. ✔
• battery's sticky broadcast and get_default_prefs use the application context. ✔
• vibration no longer leaves a find_class failure pending. ✔
• The dead clear in sensors is gone. ✔
• LAST_CHROME_STYLE is reset in set_host_activity. ✔
• activity() checks only the newest Activity and pops it if it's gone; pruning happens at registration. ✔
• UI queue: run_latest_on_ui_thread(key, f) replaces a pending task with the same key. The IME position and the system chrome use it. ✔

Not done here, on purpose:

• PR size and splitting: agreed. The upstream PRs will be cut per concern, and commits 5 and 8 will be split further (8 per package). This fork PR stays one branch so the lab can test it as a whole.
• accessibility.rs: still uses accesskit's jni 0.21 API, with its own exception behaviour. It belongs with android: expose GPUI's accessibility tree to TalkBack longbridge/gpui-mobile#25.
• performHapticFeedback: still runs on the calling thread. Moving it to the UI thread would make haptic_feedback asynchronous, which changes its Result.

I'll re-test on the phone with the lab APK (Bombatomica64/Gpui-android#24) before merging.