From 1a13ecb5965ad8eed7aa145a4856813441314e52 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 16 Aug 2023 13:24:39 -0700 Subject: [PATCH] [release/8.0] Add doc for the new invoker classes (#90636) * Add doc new invoker classes * Fix cref typo * Misc errors * Remove arg reference in 0-arg ctor summary --------- Co-authored-by: Steve Harter --- .../System/Reflection/ConstructorInvoker.cs | 62 +++++++++++++++ .../src/System/Reflection/MethodInvoker.cs | 75 +++++++++++++++++++ 2 files changed, 137 insertions(+) diff --git a/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs b/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs index 67fc0d31919759..7f3c1a227e3718 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Reflection/ConstructorInvoker.cs @@ -11,6 +11,17 @@ namespace System.Reflection { + /// + /// Invokes the method reflected by the provided . + /// + /// + /// Used for better performance than when compatibility with that method + /// is not necessary and when the caller can cache the ConstructorInvoker instance for additional invoke calls.
+ /// Unlike , the invoke methods do not look up default values for arguments when + /// is specified. In addition, the target constructor may be inlined for performance and not + /// appear in stack traces. + /// + /// public sealed partial class ConstructorInvoker { private InvokeFunc_ObjSpanArgs? _invokeFunc_ObjSpanArgs; @@ -24,6 +35,17 @@ public sealed partial class ConstructorInvoker private readonly RuntimeConstructorInfo _method; private readonly bool _needsByRefStrategy; + /// + /// Creates a new instance of ConstructorInvoker. + /// + /// + /// For performance, the resulting instance should be cached for additional calls. + /// + /// The constructor that will be invoked. + /// An instance of a ConstructorInvoker. + /// + /// The is not a runtime-based method. + /// public static ConstructorInvoker Create(ConstructorInfo constructor) { ArgumentNullException.ThrowIfNull(constructor, nameof(constructor)); @@ -46,6 +68,21 @@ private ConstructorInvoker(RuntimeConstructorInfo constructor, RuntimeType[] arg Initialize(argumentTypes, out _strategy, out _invokerArgFlags, out _needsByRefStrategy); } + /// + /// Invokes the constructor. + /// + /// + /// An instance of the class associated with the constructor. + /// + /// + /// The type that declares the method is an open generic type. + /// + /// + /// The correct number of arguments were not provided. + /// + /// + /// The calling convention or signature is not supported. + /// public object Invoke() { if (_argCount != 0) @@ -56,6 +93,14 @@ public object Invoke() return InvokeImpl(null, null, null, null); } + /// + /// Invokes the constructor using the specified parameters. + /// + /// + /// The first argument for the invoked method. + /// + /// The arguments do not match the signature of the invoked constructor. + /// public object Invoke(object? arg1) { if (_argCount != 1) @@ -66,6 +111,9 @@ public object Invoke(object? arg1) return InvokeImpl(arg1, null, null, null); } + /// + /// The first argument for the invoked method. + /// The second argument for the invoked method. public object Invoke(object? arg1, object? arg2) { if (_argCount != 2) @@ -76,6 +124,10 @@ public object Invoke(object? arg1, object? arg2) return InvokeImpl(arg1, arg2, null, null); } + /// + /// The first argument for the invoked method. + /// The second argument for the invoked method. + /// The third argument for the invoked method. public object Invoke(object? arg1, object? arg2, object? arg3) { if (_argCount !=3) @@ -86,6 +138,11 @@ public object Invoke(object? arg1, object? arg2, object? arg3) return InvokeImpl(arg1, arg2, arg3, null); } + /// + /// The first argument for the invoked method. + /// The second argument for the invoked method. + /// The third argument for the invoked method. + /// The fourth argument for the invoked method. public object Invoke(object? arg1, object? arg2, object? arg3, object? arg4) { if (_argCount != 4) @@ -137,6 +194,11 @@ private object InvokeImpl(object? arg1, object? arg2, object? arg3, object? arg4 return InvokeDirectByRef(arg1, arg2, arg3, arg4); } + /// + /// The arguments for the invoked constructor. + /// + /// The arguments do not match the signature of the invoked constructor. + /// public object Invoke(Span arguments) { int argLen = arguments.Length; diff --git a/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs b/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs index b5496c37c0cc84..66a35dbd39c74b 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Reflection/MethodInvoker.cs @@ -12,6 +12,17 @@ namespace System.Reflection { + /// + /// Invokes the method reflected by the provided . + /// + /// + /// Used for better performance than when compatibility with that method + /// is not necessary and when the caller can cache the MethodInvoker instance for additional invoke calls.
+ /// Unlike , the invoke methods do not look up default values for arguments when + /// is specified. In addition, the target method may be inlined for performance and not + /// appear in stack traces. + /// + /// public sealed partial class MethodInvoker { private InvokeFunc_ObjSpanArgs? _invokeFunc_ObjSpanArgs; @@ -26,6 +37,17 @@ public sealed partial class MethodInvoker private readonly bool _needsByRefStrategy; private readonly bool _isStatic; + /// + /// Creates a new instance of MethodInvoker. + /// + /// + /// For performance, the resulting instance should be cached for additional calls. + /// + /// The method that will be invoked. + /// An instance of a MethodInvoker. + /// + /// The is not a runtime-based method. + /// public static MethodInvoker Create(MethodBase method) { ArgumentNullException.ThrowIfNull(method, nameof(method)); @@ -60,6 +82,32 @@ private MethodInvoker(MethodBase method, RuntimeType[] argumentTypes) Initialize(argumentTypes, out _strategy, out _invokerArgFlags, out _needsByRefStrategy); } + /// + /// Invokes the method using the specified parameters. + /// + /// + /// The object on which to invoke the method. If the method is static, this argument is ignored. + /// + /// + /// An object containing the return value of the invoked method, + /// or null if the invoked method does not have a return value. + /// + /// + /// The obj parameter is null and the method is not static. + /// + /// -or- + /// + /// The method is not declared or inherited by the class of obj. + /// + /// + /// The type that declares the method is an open generic type. + /// + /// + /// The correct number of arguments were not provided. + /// + /// + /// The calling convention or signature is not supported. + /// public object? Invoke(object? obj) { if (_argCount != 0) @@ -70,6 +118,12 @@ private MethodInvoker(MethodBase method, RuntimeType[] argumentTypes) return InvokeImpl(obj, null, null, null, null); } + /// + /// The object on which to invoke the method. If the method is static, this argument is ignored. + /// The first argument for the invoked method. + /// + /// The arguments do not match the signature of the invoked method. + /// public object? Invoke(object? obj, object? arg1) { if (_argCount != 1) @@ -80,6 +134,10 @@ private MethodInvoker(MethodBase method, RuntimeType[] argumentTypes) return InvokeImpl(obj, arg1, null, null, null); } + /// + /// The object on which to invoke the method. If the method is static, this argument is ignored. + /// The first argument for the invoked method. + /// The second argument for the invoked method. public object? Invoke(object? obj, object? arg1, object? arg2) { if (_argCount != 2) @@ -90,6 +148,11 @@ private MethodInvoker(MethodBase method, RuntimeType[] argumentTypes) return InvokeImpl(obj, arg1, arg2, null, null); } + /// + /// The object on which to invoke the method. If the method is static, this argument is ignored. + /// The first argument for the invoked method. + /// The second argument for the invoked method. + /// The third argument for the invoked method. public object? Invoke(object? obj, object? arg1, object? arg2, object? arg3) { if (_argCount != 3) @@ -100,6 +163,12 @@ private MethodInvoker(MethodBase method, RuntimeType[] argumentTypes) return InvokeImpl(obj, arg1, arg2, arg3, null); } + /// + /// The object on which to invoke the method. If the method is static, this argument is ignored. + /// The first argument for the invoked method. + /// The second argument for the invoked method. + /// The third argument for the invoked method. + /// The fourth argument for the invoked method. public object? Invoke(object? obj, object? arg1, object? arg2, object? arg3, object? arg4) { if (_argCount != 4) @@ -156,6 +225,12 @@ private MethodInvoker(MethodBase method, RuntimeType[] argumentTypes) return InvokeDirectByRef(obj, arg1, arg2, arg3, arg4); } + /// + /// The object on which to invoke the method. If the method is static, this argument is ignored. + /// The arguments for the invoked method. + /// + /// The arguments do not match the signature of the invoked method. + /// public object? Invoke(object? obj, Span arguments) { int argLen = arguments.Length;