Add more detail to GetFunctionPointerForDelegate docs (#11401)

jkotas · web-flow · commit cbd917d41b53 · 2025-06-10T12:16:58.000-07:00
diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml
@@ -3989,10 +3989,15 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho
 
  You must manually keep the delegate from being collected by the garbage collector from managed code. The garbage collector does not track references to unmanaged code.
 
+ This API is unsupported in environments that don't support dynamic entry-point allocation, such as `ProcessDynamicCodePolicy` on Windows, `execmem off` in SELinux, and WebAssembly.
+ 
+ It is recommended to use function pointers and <xref:System.Runtime.InteropServices.UnmanagedCallersOnlyAttribute> instead. Function pointers are more efficient, easier to use correctly, and supported in all environments.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">The <paramref name="d" /> parameter is a generic type definition.</exception>
         <exception cref="T:System.ArgumentNullException">The <paramref name="d" /> parameter is <see langword="null" />.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">Dynamic entrypoint allocation is not supported in the current environment.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetFunctionPointerForDelegate&lt;TDelegate&gt;">
@@ -4058,11 +4063,15 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho
  The delegate `d` is converted to a function pointer that can be passed to unmanaged code by using [the default platform calling convention](/dotnet/standard/native-interop/calling-conventions#platform-default-calling-convention). You can set the calling convention by applying the <xref:System.Runtime.InteropServices.UnmanagedFunctionPointerAttribute> to the delegate.
 
  You must manually keep the delegate from being collected by the garbage collector from managed code. The garbage collector does not track references to unmanaged code.
-
+ 
+ This API is unsupported in environments that don't support dynamic entry-point allocation, such as `ProcessDynamicCodePolicy` on Windows, `execmem off` in SELinux, and WebAssembly.
+ 
+ It is recommended to use function pointers and <xref:System.Runtime.InteropServices.UnmanagedCallersOnlyAttribute> instead. Function pointers are more efficient, easier to use correctly, and supported in all environments.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">The <paramref name="d" /> parameter is a generic type definition.</exception>
         <exception cref="T:System.ArgumentNullException">The <paramref name="d" /> parameter is <see langword="null" />.</exception>
+        <exception cref="T:System.PlatformNotSupportedException">Dynamic entrypoint allocation is not supported in the current environment.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetHINSTANCE">
