[generator] Prototype typed UCO binding callbacks

[simonrozsival]

Generated Java binding callbacks currently retain the legacy delegate registration shape even when the trimmable typemap registers native methods through generated [UnmanagedCallersOnly] entry points.

For each eligible callback, Mono.Android.dll contains all of:

cb_* delegate field
Get*Handler connector method
n_* -> JniMarshal.SafeInvoke*
__n_* -> peer/argument marshaling and managed invocation

The trimmable typemap then emits another UCO method that forwards to n_*.

This experimental .NET 12 direction removes the delegate field, connector method, and typemap forwarding method. The binding assembly owns the UCO entry point, while a shared typed helper owns common transition and marshaling work:

[UnmanagedCallersOnly]
static int n_GetFlags (IntPtr jnienv, IntPtr native__this, IntPtr native_value)
    => JniMarshalTyped.SafeInvokeMarshaled_OS<MyType, Other, int> (
        jnienv, native__this, native_value, &__n_GetFlags);

static int __n_GetFlags (MyType self, Other? value)
    => self.GetFlags (value);

The trimmable typemap's RegisterNatives implementation takes the external UCO method's function pointer directly. Managed code never calls the UCO method.

Why this is worth exploring

Mono.Android.dll contains approximately 30,000 generated native callbacks. Small repeated shapes therefore have multi-megabyte consequences.

All four prototypes removed roughly 9–10% from the untrimmed Mono.Android.dll. The ordering changed between Debug and Release: typed was smallest in Debug, while the non-generic ABI-shape prototype was smallest in Release.

Debug API 37 variant	Mono.Android.dll	Change from baseline
Current baseline	45,262,848 B	—
Raw UCO + existing SafeInvoke	40,830,976 B	-4,431,872 B (-9.8%)
Inline transition/marshaling	41,093,632 B	-4,169,216 B (-9.2%)
Non-generic ABI-shape helpers	40,794,624 B	-4,468,224 B (-9.9%)
Typed marshaling helpers (this PR)	40,740,864 B	-4,521,984 B (-10.0%)

The final isolated Release builds, which better represent shipped framework binaries, produced:

Release API 37 variant	Mono.Android.dll	Change from baseline
Current baseline	41,879,040 B	—
Raw UCO + existing SafeInvoke	37,956,096 B	-3,922,944 B
Typed marshaling helpers (this PR)	38,040,064 B	-3,838,976 B
Inline transition/marshaling	38,223,872 B	-3,655,168 B
Non-generic ABI-shape helpers	37,912,576 B	-3,966,464 B

In Release, typed is 83,968 bytes larger than raw and 127,488 bytes larger than ABI-shape. This PR selects typed as the design prototype because it expresses the desired sharing boundary most directly, not because it conclusively wins every size configuration.

In the Debug comparison, typed versus raw at equal UCO coverage showed the following shape trade-off:

Metric	Raw UCO	Typed UCO
IL bytes	8,337,025	8,075,908
Parameter rows	294,244	278,297
Standalone signature rows	23,977	15,477
MethodSpec rows	8,669	17,307
MethodDef rows	201,579	201,641

Typed sharing reduces repeated IL and signatures, at the cost of 8,638 additional generic method instantiations. This trade-off, and the configuration-dependent size ordering, need more NativeAOT and Release-app investigation before the design can ship.

Implementation

Generated binding callbacks

An internal generator option enables the new format. It is disabled by default.

For supported callbacks, the generator:

1. Emits [UnmanagedCallersOnly] directly on n_*.
2. Omits the cb_* field and Get*Handler connector method.
3. Calls one of 60 shape-specific JniMarshalTyped helpers.
4. Emits a small managed function-pointer target containing the binding-specific invocation.

The shared helper owns:

• bridge-processing synchronization;
• BeginMarshalMethod;
• managed peer lookup for this;
• supported object-argument conversion;
• invocation through a managed function pointer;
• JNI local-reference conversion for object returns;
• OnUserUnhandledException; and
• EndMarshalMethod.

Shape names encode object/scalar arguments and void/scalar/object returns. Object returns use IJavaObject? so covariant binding returns do not require another generic type argument.

Helper naming and generation

The suffix after SafeInvokeMarshaled_ concatenates one character for each Java method argument, followed by one character for the return value:

• argument O: JNI object reference, converted to a managed peer with GetObject<T>();
• argument S: unmanaged JNI scalar, forwarded unchanged;
• return X: void;
• return S: unmanaged scalar, forwarded unchanged; and
• return O: managed IJavaObject?, converted to a JNI local reference.

The callback receiver (self/TPeer) is implicit and is not encoded in the suffix.

Examples:

Helper suffix	Java arguments	Return
X	none	void
S	none	scalar
O	none	object
OX	object	void
OS	object	scalar
OO	object	object
SOX	scalar, object	void
OSS	object, scalar	scalar
OOO	object, object	object
SSSSX	four scalars	void

These helpers are generated from src/Mono.Android/Java.Interop/JniMarshalTyped.tt using T4; JniMarshalTyped.cs is the checked-in generated output. Regenerate it with:

t4 JniMarshalTyped.tt -o JniMarshalTyped.cs

The template emits every object/scalar argument combination for arities 0–3 and the all-scalar form for arities 4–8, each with X, S, and O return variants: 60 helpers in total. Shapes requiring different lifetime or cleanup semantics are intentionally not generated and retain the raw JniMarshal.SafeInvoke* path.

Explicit fallbacks

The typed helper is used for 19,623 of 29,979 callbacks in API 37 (65.5%).

Another 8,527 callbacks (28.5%) are still direct UCO methods but retain the existing raw JniMarshal.SafeInvoke* body. These include semantics that should not be centralized without further work:

Raw-UCO fallback reason	Callbacks
String parameter or return	4,537
Array/copy-back parameter or array return	1,546
Collection projection	693
ICharSequence/formatted method	551
Java-generic method with erased helper type	462
Helper arity/shape tail	311
Stream projection	197
Generic type argument in return	147
Sender parameter	45
Generic-marshaling override	24
XML parser projection	13

The remaining 1,818 callbacks (6.1%) are declared on generic types and keep the complete legacy delegate/connector shape. CLR UCO methods cannot be declared on generic types. A future direction is a generated non-generic host/bridge inspired by #12563.

Versioned assembly format and typemap support

New-format binding assemblies carry a versioned JavaPeerCallbackFormat assembly marker.

The scanner uses the marker as a format gate and validates the actual [UnmanagedCallersOnly] method per callback. The model records whether RegisterNatives should target:

• an existing UCO method in the binding assembly; or
• a generated typemap wrapper for an old connector-based assembly.

This permits marked and legacy binding assemblies in the same application. External callbacks are referenced with ldftn/MemberRef; they are never called from managed IL.

What the broader experiment taught us

Promising framework-size result

Removing repeated delegate registration infrastructure saves approximately 9–10% of the untrimmed framework assembly. The typed version shares more binding-specific IL than the conservative raw version and has the clearest generated shape, while the ABI-shape version currently has the smallest Release framework DLL.

Trimmed app size is not yet a demonstrated win

Five feature-verified, trimmed, Release, arm64 Maui.Controls.Sample APKs were built with CoreCLR and the trimmable typemap. The generated callback shapes survived trimming and remained distinguishable:

• baseline: connector/delegate callbacks;
• raw: UCO plus SafeInvoke;
• typed: UCO plus JniMarshalTyped;
• inline: fully inlined UCO body;
• ABI-shape: UCO plus non-generic ABI helper.

The post-trim result did not preserve the untrimmed ordering:

Variant	Signed APK	Compressed assembly store	Trimmed Mono.Android.dll
Baseline	33,304,195 B	7,456,014 B	1,113,600 B
Raw	33,304,195 B	7,456,145 B	1,115,136 B
Typed	33,300,099 B	7,452,310 B	1,124,352 B
Inline	33,300,099 B	7,449,744 B	1,114,112 B
ABI-shape	33,304,195 B	7,456,333 B	1,121,792 B

Whole-APK differences are within one 4 KiB signing-alignment page and independent publishes introduced unrelated R2R nondeterminism. This experiment therefore demonstrates a large SDK/framework-size reduction, but not a final application-size reduction.

No valid performance conclusion yet

Earlier startup and callback-throughput runs were withdrawn after auditing found that some artifacts had been rebuilt without the experimental opt-in and an initial callback benchmark exercised an app-generated ACW instead of a modified framework binding callback.

The benchmark was subsequently redesigned around verified generated framework callbacks, but benchmarking was stopped before collecting final results. This PR intentionally makes no startup or throughput claim.

Compatibility and remaining work

This is a draft design prototype, not yet suitable for enabling by default.

• New-format assemblies require AndroidTypeMapImplementation=trimmable. The legacy reflection registration path tries to resolve the retained connector string and cannot find the omitted connector method. The SDK must enforce this combination at build time.
• If a marked assembly's UCO method cannot be resolved, generation must fail rather than emit a managed forwarding call to a UCO method.
• Generic declaring types need a non-generic callback host/bridge or must continue using the measured legacy fallback.
• The 60 JniMarshalTyped helpers and callback-format contract currently add API surface. Their final visibility, naming, and compatibility contract need design review.
• Strings, arrays, collection projections, streams, and copy-back semantics need dedicated helper designs before increasing typed coverage.
• NativeAOT code-size impact from the additional MethodSpec instantiations requires a controlled measurement.
• The retained _JniMarshal_* delegate type declarations are still needed by hand-written JNINativeWrapper.g.cs. Removing them is a separate follow-up.
• [Export], constructor, and direct-managed-dispatch callback paths still need alignment with the final format.
• Build/app tests should cover mixed old/new binding packages, boolean/character ABI compatibility, generic declaring types, and failure diagnostics.

Validation

• Java.Interop generator tests: 495 passed, including six new callback-format tests.
• Trimmable typemap tests: 786 passed, including eight new scanner/model/emitter tests and a marked fixture assembly.
• Mono.Android.dll builds with the feature disabled and enabled.
• All 28,156 emitted UCO methods were structurally validated as static, non-generic, declared on non-generic types, and fully blittable.
• IL scan: zero managed calls to UCO methods across 192,336 method bodies.
• Maui.Controls.Sample builds with CoreCLR + trimmable typemap; extracted post-trim assemblies retain the expected typed callback format.

---

• Useful description of why the change is necessary.
• Links to issues fixed — experimental investigation; no issue is closed.
• Unit tests