[linker] Convert the EnsureUIThread optimization to a trimmer feature switch. Fixes #26104. (#26140)

Replace the hand-written IL rewrite of `[NS|UI]Application.EnsureUIThread` with an `ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls` trimmer feature switch, driven by a new `$(CheckForIllegalCrossThreadCalls)` MSBuild property (defaults to the build configuration: on for debug, off for release).

* Remove `ProcessEnsureUIThread` (and its case) from the linker's `OptimizeGeneratedCode` step, and mark the now-orphaned `--optimize=remove-uithread-checks` flag as removed (following the existing `inline-intptr-size` convention).
* Emit the `ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls` `RuntimeHostConfigurationOption` from `Xamarin.Shared.Sdk.targets` and stub the `EnsureUIThread` method body via ILLink substitutions on all four platforms when the feature is off.
* Make `[NS|UI]Application.CheckForIllegalCrossThreadCalls` trimmable when the checks are off, without an API break: drop the field's `= true` initializer and instead set it from the application startup path, guarded by an internal feature-switched `Runtime.CheckForIllegalCrossThreadCalls` getter. When the feature is off the getter substitutes to a constant `false`, so the assignment is dead-code-eliminated and — with `EnsureUIThread` also stubbed — the field can be trimmed away entirely.
* Document the new `$(CheckForIllegalCrossThreadCalls)` property and update `optimizations.md`.

Because the property is emitted as a runtime feature switch, it also takes effect when trimming is disabled (the field reflects the property value at runtime); trimming is only needed to physically remove the check code.

Add `EnsureUIThreadChecksTest` (with a dedicated `EnsureUIThreadApp` project that keeps `EnsureUIThread` reachable) verifying the feature switch value and that, in the app bundle, `EnsureUIThread` is stubbed and the field is trimmed when the checks are off (iOS + macOS).

Fixes #26104

🤖 Pull request created by Copilot

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Rolf Bjarne Kvinge <rokvin@microsoft.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

docs/building-apps/build-properties.md

@@ -197,6 +197,27 @@ The default value of this property `false` in .NET 9, and `true` in .NET 10+.
 > [!NOTE]
 > File an issue if you find that you need to disable this feature, as it's possible that the option to disable it will be removed in future.
 
+## CheckForIllegalCrossThreadCalls
+
+Controls whether the UI thread checks (the `[NS|UI]Application.EnsureUIThread`
+calls the generated bindings emit for UI code) are performed.
+
+When set to `true`, the checks are enabled: accessing UI API off the UI thread
+throws an exception. When set to `false`, the checks are disabled.
+
+This property is emitted as the `ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls`
+runtime feature switch, so it takes effect even when trimming is disabled: the
+`[NS|UI]Application.CheckForIllegalCrossThreadCalls` field reflects the property
+value at runtime, and the checks are enabled or disabled accordingly.
+
+When trimming is enabled and the checks are disabled, ILLink additionally stubs
+the `[NS|UI]Application.EnsureUIThread` method body and trims away the
+`CheckForIllegalCrossThreadCalls` field, making the app slightly smaller and
+faster.
+
+If this value is not specified, the checks are kept in debug builds and removed
+in release builds.
+
 ## CodesignAllocate
 
 The path to the `codesign_allocate` tool.

docs/website/optimizations.md

@@ -16,8 +16,15 @@ Xamarin.iOS and Xamarin.Mac apps.
 
 ## Remove UIApplication.EnsureUIThread / NSApplication.EnsureUIThread
 
-Removes calls to [UIApplication.EnsureUIThread][1] (for Xamarin.iOS) or
-`NSApplication.EnsureUIThread` (for Xamarin.Mac).
+> [!NOTE]
+> This optimization has been replaced by the `CheckForIllegalCrossThreadCalls`
+> MSBuild property, which sets the
+> `ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls` trimmer feature switch.
+> The `--optimize=[+|-]remove-uithread-checks` flag is no longer applied and has
+> no effect.
+
+Removes calls to [UIApplication.EnsureUIThread][1] (for .NET for iOS) or
+`NSApplication.EnsureUIThread` (for .NET for macOS).
 
 This optimization will change the following type of code:
 
@@ -43,7 +50,7 @@ methods with the `[BindingImpl (BindingImplOptions.Optimizable)]` attribute.
 
 By default it's enabled for release builds.
 
-The default behavior can be overridden by passing `--optimize=[+|-]remove-uithread-checks` to mtouch/mmp.
+Set the `CheckForIllegalCrossThreadCalls` MSBuild property to override the default behavior.
 
 [1]: /dotnet/api/UIKit.UIApplication.EnsureUIThread
 

dotnet/targets/Xamarin.Shared.Sdk.targets

@@ -755,6 +755,15 @@
 			<!-- Set default ValidateObjectPointers value -->
 			<_ValidateObjectPointers Condition="'$(_ValidateObjectPointers)' == ''">false</_ValidateObjectPointers>
 
+			<!--
+				Set the 'ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls' feature switch value. When false, ILLink stubs
+				the [NS|UI]Application.EnsureUIThread method body (so the UI thread checks are removed). A user-specified
+				$(CheckForIllegalCrossThreadCalls) always wins; otherwise we keep the checks in debug builds and remove them in
+				release builds (matching the old 'remove-uithread-checks' optimization default).
+			-->
+			<_CheckForIllegalCrossThreadCalls Condition="'$(CheckForIllegalCrossThreadCalls)' != ''">$(CheckForIllegalCrossThreadCalls)</_CheckForIllegalCrossThreadCalls>
+			<_CheckForIllegalCrossThreadCalls Condition="'$(_CheckForIllegalCrossThreadCalls)' == ''">$(_BundlerDebug)</_CheckForIllegalCrossThreadCalls>
+
 			<_CustomLinkerOptions>
 				AreAnyAssembliesTrimmed=$(_AreAnyAssembliesTrimmed)
 				AssemblyName=$(AssemblyName).dll
@@ -904,6 +913,7 @@
 			<RuntimeHostConfigurationOption Include="ObjCRuntime.Runtime.IsCoreCLR" Value="true" Trim="true" Condition="'$(UseMonoRuntime)' != 'true'" />
 			<RuntimeHostConfigurationOption Include="ObjCRuntime.Runtime.IsCoreCLR" Value="false" Trim="true" Condition="'$(UseMonoRuntime)' == 'true'" />
 			<RuntimeHostConfigurationOption Include="ObjCRuntime.Class.ValidateObjectPointers" Value="$(_ValidateObjectPointers)" Trim="true" />
+			<RuntimeHostConfigurationOption Include="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" Value="$(_CheckForIllegalCrossThreadCalls)" Trim="true" />
 
 			<!-- Configure System.Net.Http Native Handlers -->
 			<RuntimeHostConfigurationOption Include="System.Net.Http.NativeHandler.UseNSUrlSessionHandler" Value="$(_IsNSUrlSessionHandlerFeature)" Trim="true" />

src/AppKit/NSApplication.cs

@@ -32,9 +32,8 @@
 
 namespace AppKit {
 	public partial class NSApplication : NSResponder {
-		/// <summary>To be added.</summary>
-		///         <remarks>To be added.</remarks>
-		public static bool CheckForIllegalCrossThreadCalls = true;
+		/// <inheritdoc cref="Runtime.CheckForIllegalCrossThreadCalls" />
+		public static bool CheckForIllegalCrossThreadCalls;
 		/// <summary>To be added.</summary>
 		///         <remarks>To be added.</remarks>
 		public static bool CheckForEventAndDelegateMismatches = true;
@@ -53,6 +52,12 @@ public static void Init ()
 
 		internal static void InitializeApplication ()
 		{
+			// The linker replaces the 'Runtime.CheckForIllegalCrossThreadCalls' getter with a constant value, so when the UI
+			// thread checks are disabled the assignment below (and the 'CheckForIllegalCrossThreadCalls' field
+			// itself, unless something else references it) is trimmed away.
+			if (Runtime.CheckForIllegalCrossThreadCalls)
+				CheckForIllegalCrossThreadCalls = true;
+
 			SynchronizationContext.SetSynchronizationContext (new AppKitSynchronizationContext ());
 		}
 

src/ILLink.Substitutions.MacCatalyst.xml

@@ -16,6 +16,8 @@
       <method signature="System.Boolean GetIsARM64CallingConvention()" body="stub" feature="ObjCRuntime.Runtime.IsARM64CallingConvention" featurevalue="true" value="true" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="false" value="false" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="true" value="true" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" value="false" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="true" value="true" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="false" value="false" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="true" value="true" />
       <method signature="System.Boolean get_UseCFNetworkHandler()" body="stub" feature="System.Net.Http.NativeHandler.UseCFNetworkHandler" featurevalue="false" value="false" />
@@ -28,6 +30,7 @@
       <method signature="System.Boolean get_ValidateObjectPointers()" body="stub" feature="ObjCRuntime.Class.ValidateObjectPointers" featurevalue="true" value="true" />
     </type>
     <type fullname="UIKit.UIApplication">
+      <method signature="System.Void EnsureUIThread()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" />
       <method signature="System.Void EnsureEventAndDelegateAreNotMismatched(System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
       <method signature="System.Void EnsureDelegateAssignIsNotOverwritingInternalDelegate(System.Object,System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
     </type>

src/ILLink.Substitutions.iOS.xml

@@ -18,6 +18,8 @@
       <method signature="System.Boolean GetIsARM64CallingConvention()" body="stub" feature="ObjCRuntime.Runtime.IsARM64CallingConvention" featurevalue="true" value="true" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="false" value="false" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="true" value="true" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" value="false" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="true" value="true" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="false" value="false" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="true" value="true" />
       <method signature="System.Boolean get_UseCFNetworkHandler()" body="stub" feature="System.Net.Http.NativeHandler.UseCFNetworkHandler" featurevalue="false" value="false" />
@@ -45,6 +47,7 @@
       <method signature="System.Boolean get_ValidateObjectPointers()" body="stub" feature="ObjCRuntime.Class.ValidateObjectPointers" featurevalue="true" value="true" />
     </type>
     <type fullname="UIKit.UIApplication">
+      <method signature="System.Void EnsureUIThread()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" />
       <method signature="System.Void EnsureEventAndDelegateAreNotMismatched(System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
       <method signature="System.Void EnsureDelegateAssignIsNotOverwritingInternalDelegate(System.Object,System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
     </type>

src/ILLink.Substitutions.macOS.xml

@@ -15,6 +15,8 @@
       <method signature="System.Boolean GetIsARM64CallingConvention()" body="stub" feature="ObjCRuntime.Runtime.IsARM64CallingConvention" featurevalue="true" value="true" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="false" value="false" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="true" value="true" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" value="false" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="true" value="true" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="false" value="false" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="true" value="true" />
       <method signature="System.Boolean get_UseCFNetworkHandler()" body="stub" feature="System.Net.Http.NativeHandler.UseCFNetworkHandler" featurevalue="false" value="false" />
@@ -27,6 +29,7 @@
       <method signature="System.Boolean get_ValidateObjectPointers()" body="stub" feature="ObjCRuntime.Class.ValidateObjectPointers" featurevalue="true" value="true" />
     </type>
     <type fullname="AppKit.NSApplication">
+      <method signature="System.Void EnsureUIThread()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" />
       <method signature="System.Void EnsureEventAndDelegateAreNotMismatched(System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
       <method signature="System.Void EnsureDelegateAssignIsNotOverwritingInternalDelegate(System.Object,System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
     </type>

src/ILLink.Substitutions.tvOS.xml

@@ -18,6 +18,8 @@
       <method signature="System.Boolean GetIsARM64CallingConvention()" body="stub" feature="ObjCRuntime.Runtime.IsARM64CallingConvention" featurevalue="true" value="true" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="false" value="false" />
       <method signature="System.Boolean get_DynamicRegistrationSupported()" body="stub" feature="ObjCRuntime.Runtime.DynamicRegistrationSupported" featurevalue="true" value="true" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" value="false" />
+      <method signature="System.Boolean get_CheckForIllegalCrossThreadCalls()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="true" value="true" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="false" value="false" />
       <method signature="System.Boolean get_IsTrimmableStaticRegistrar()" body="stub" feature="ObjCRuntime.Runtime.IsTrimmableStaticRegistrar" featurevalue="true" value="true" />
       <method signature="System.Boolean get_UseCFNetworkHandler()" body="stub" feature="System.Net.Http.NativeHandler.UseCFNetworkHandler" featurevalue="false" value="false" />
@@ -45,6 +47,7 @@
       <method signature="System.Boolean get_ValidateObjectPointers()" body="stub" feature="ObjCRuntime.Class.ValidateObjectPointers" featurevalue="true" value="true" />
     </type>
     <type fullname="UIKit.UIApplication">
+      <method signature="System.Void EnsureUIThread()" body="stub" feature="ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls" featurevalue="false" />
       <method signature="System.Void EnsureEventAndDelegateAreNotMismatched(System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
       <method signature="System.Void EnsureDelegateAssignIsNotOverwritingInternalDelegate(System.Object,System.Object,System.Type)" body="stub" feature="System.Diagnostics.Debugger.IsSupported" featurevalue="false" />
     </type>

src/ObjCRuntime/Runtime.cs

@@ -290,6 +290,26 @@ public static bool DynamicRegistrationSupported {
 		[BindingImpl (BindingImplOptions.Optimizable)]
 		internal static bool UseCFNetworkHandler => AppContext.TryGetSwitch ("System.Net.Http.NativeHandler.UseCFNetworkHandler", out bool isDefault) ? isDefault : false;
 
+		// The linker may turn calls to this property into a constant
+		/// <summary>Determines whether the debug builds will enforce that calls done to AppKit/UIKit APIs are only issued from the UI thread.</summary>
+		/// <remarks>
+		///   <para>
+		///     On debug builds, the runtime will enforce that calls made to
+		///     AppKit/UIKit APIs are only done from the main thread. This is
+		///     useful to spot code that could inadvertently use AppKit/UIKit from
+		///     a non-UI thread which can corrupt state and could lead to
+		///     very hard to debug problems.
+		///   </para>
+		///   <para>
+		///     But sometimes it might be useful to disable this check,
+		///     either because you can ensure that AppKit/UIKit is not in use at
+		///     this point or because the APIs in question might have later been
+		///     relaxed or made thread safe by Apple.
+		///   </para>
+		/// </remarks>
+		[BindingImpl (BindingImplOptions.Optimizable)]
+		internal static bool CheckForIllegalCrossThreadCalls => AppContext.TryGetSwitch ("ObjCRuntime.Runtime.CheckForIllegalCrossThreadCalls", out bool enabled) ? enabled : true;
+
 		internal static bool Initialized {
 			get { return initialized; }
 		}

src/UIKit/UIApplication.cs

@@ -26,25 +26,8 @@ public UIKitThreadAccessException () : base ("UIKit Consistency error: you are c
 
 	public partial class UIApplication
 	: UIResponder {
-		/// <summary>Determines whether the debug builds of MonoTouch will enforce that calls done to UIKit are only issued from the UI thread.</summary>
-		///         <remarks>
-		///           <para>
-		///             On debug builds, MonoTouch will enforce that calls made to
-		///             UIKit APIs are only done from the UIKit thread.  This is
-		///             useful to spot code that could inadvertently use UIKit from
-		///             a non-UI thread which can corrupt the UIKit state and could
-		///             lead to very hard to debug problems.
-		///           </para>
-		///           <para>
-		///             But sometimes it might be useful to disable this check,
-		///             either because you can ensure that UIKit is not in use at
-		///             this point or because MonoTouch might be enforcing the
-		///             checks in APIs that might have later been relaxed or made
-		///             thread safe by iOS.
-		///
-		///           </para>
-		///         </remarks>
-		public static bool CheckForIllegalCrossThreadCalls = true;
+		/// <inheritdoc cref="Runtime.CheckForIllegalCrossThreadCalls" />
+		public static bool CheckForIllegalCrossThreadCalls;
 		/// <summary>If <see langword="true" />, the system will try to diagnose potential mistakes where events and delegate-object overrides are in conflict.</summary>
 		public static bool CheckForEventAndDelegateMismatches = true;
 
@@ -70,6 +53,12 @@ static int UIApplicationMain (int argc, /* char[]* */ string []? argv, /* NSStri
 		// NOTE: must be called from the main thread, e.g. for extensions
 		internal static void InitializeApplication ()
 		{
+			// The linker replaces the 'Runtime.CheckForIllegalCrossThreadCalls' getter with a constant value, so when the UI
+			// thread checks are disabled the assignment below (and the 'CheckForIllegalCrossThreadCalls' field
+			// itself, unless something else references it) is trimmed away.
+			if (Runtime.CheckForIllegalCrossThreadCalls)
+				CheckForIllegalCrossThreadCalls = true;
+
 			SynchronizationContext.SetSynchronizationContext (new UIKitSynchronizationContext ());
 		}