[Version 13.0] Feature support for Overload resolution priority

standard/attributes.md

@@ -508,6 +508,7 @@
 - `System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute` ([§23.5.11.1](attributes.md#235111-the-setsrequiredmembers-attribute)) and `System.Runtime.CompilerServices.RequiredMemberAttribute` ([§23.5.11.2](attributes.md#235112-the-requiredmember-attribute)), which are used in required-member contexts ([§15.7.1](classes.md#1571-general)).
 - `System.Runtime.CompilerServices.CollectionBuilderAttribute` ([§23.5.12](attributes.md#23512-the-collectionbuilder-attribute)), which designates a collection type as having a collection-creation method.
 - `System.Runtime.CompilerServices.InlineArrayAttribute` ([§23.5.13](attributes.md#23513-the-inlinearray-attribute)), which marks a struct type as an inline array type ([§16.6](structs.md#166-inline-arrays)).
+- `System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute` (§OvrldResPriAttribute), which specifies the priority of a member during overload resolution.
 
 The Nullable static analysis attributes ([§23.5.7](attributes.md#2357-code-analysis-attributes)) can improve the correctness of warnings generated for nullabilities and null states ([§8.9.5](types.md#895-nullabilities-and-null-states)).
 
@@ -1242,11 +1243,11 @@
 
 This attribute may can be applied to any `ref` and it changes the ref-safe-context to be one level wider than its default. For example:
 
 | UnscopedRef applied to | Original ref-safe-context | New ref-safe-context |
 | --- | --- | --- |
 | instance member | function-member | return-only |
 | `in` / `ref` parameter | return-only | caller-context |
 | `out` parameter | function-member | return-only |
 
 When applying this attribute to an instance method of a struct it modifies the implicit `this` parameter; that is, `this` acts as an unannotated `ref` of the same type.
 
@@ -1576,10 +1577,73 @@
 The attribute can be applied to a class, struct, ref struct, or interface. The attribute is not inherited although it can be applied to a base class or an abstract class.
 
 The builder type shall be a non-generic class or struct.
+
 ### 23.5.13 The InlineArray attribute
 
 The attribute `InlineArray` is used to identify a non-record struct as an inline array type. For further information and examples of its use, see [§16.6](structs.md#166-inline-arrays).
 
+### §OvrldResPriAttribute The OverloadResolutionPriority attribute
+
+The attribute `OverloadResolutionPriority` is used to specify the priority of a member during overload resolution, as an `int` argument to the constructor. The absence of this attribute is equivalent to its presence with an argument of `0`. The higher the number, the higher the priority. All overloads with a lower priority than the highest overload priority are removed from the set of applicable matches.
+
+A library author might use this attribute to ensure that a new, better overload is preferred over an existing one, to reduce memory allocation, for example. This attribute informs the compiler which overload should be preferred.
+
+> <!-- Example: {template:"standalone-console", name:"OverloadResolutionPriority1", expectedOutput:["Span"]} -->
+> *Example*: Consider the following:
+>
+> ```csharp
+> class Program
+> {
+>     static void Main()
+>     {
+>         var c = new C();
+>         int[] arr = [1, 2, 3];
+>         c.M(arr);   // Prints "Span"
+>     }
+> }
+> class C
+> {
+>     [OverloadResolutionPriority(1)]
+>     public void M(params ReadOnlySpan<int> s) => Console.WriteLine("Span");
+>     public void M(params int[] a) => Console.WriteLine("Array");
+> }
+> ```
+>
+> The second method has an implicit priority of zero, and in the absence of the explicit attribute, the second of the overloads would be invoked. However, with the attribute present, the first is invoked instead.
+>
+> <!-- Example: {template:"standalone-console", name:"OverloadResolutionPriority2"} -->
+> Certain uses of this attribute can make a member uncallable, as follows:
+>
+> ```csharp
+> class Program
+> {
+>     static void Main()
+>     {
+>         var c = new C();
+>         c.M1(1); // Calls C3.M1(long), not M1(int)
+>         c.M2(1); // Calls C3.M2(int, string), not M2(int)
+>         c.M3("abc"); // Calls C3.M3(object), not M3(string)
+>     }
+> }
+> class C
+> {
+>     public void M1(int i) { }
+>     [OverloadResolutionPriority(1)]
+>     public void M1(long l) { }
+>
+>     [Conditional("DEBUG")]
+>     public void M2(int i) { }
+>     [OverloadResolutionPriority(1), Conditional("DEBUG")]
+>     public void M2(int i, [CallerArgumentExpression(nameof(i))] string s = "") { }
+>
+>     public void M3(string s) { }
+>     [OverloadResolutionPriority(1)]
+>     public void M3(object o) { }
+> }
+> ```
+>
+> *end example*
+
 ## 23.6 Attributes for interoperation
 
 For interoperation with other languages, an indexer may be implemented using indexed properties. If no `IndexerName` attribute is present for an indexer, then the name `Item` is used by default. The `IndexerName` attribute enables a developer to override this default and specify a different name.

standard/expressions.md

@@ -1064,9 +1064,15 @@ Overload resolution is a binding-time mechanism for selecting the best function
 
 Each of these contexts defines the set of candidate function members and the list of arguments in its own unique way. For instance, the set of candidates for a method invocation does not include methods marked override ([§12.5](expressions.md#125-member-lookup)), and methods in a base class are not candidates if any method in a derived class is applicable ([§12.8.10.2](expressions.md#128102-method-invocations)).
 
+Each method has an ***overload resolution priority*** of type `int` that is used during the process of resolving a method group. By default, that priority is zero. Its value can be set via `OverloadResolutionPriorityAttribute` (§OvrldResPriAttribute). The overload resolution priority of a member comes from the least-derived declaration of that member. Overload resolution priority is not inherited or inferred from any interface members a type member may implement, and given a member `Mx` that implements an interface member `Mi`, no warning is issued if `Mx` and `Mi` have different overload resolution priorities.
+
 Once the candidate function members and the argument list have been identified, the selection of the best function member is the same in all cases:
 
 - First, the set of candidate function members is reduced to those function members that are applicable with respect to the given argument list ([§12.6.4.2](expressions.md#12642-applicable-function-member)). If this reduced set is empty, a compile-time error occurs.
+- Then, the reduced set of candidate members is grouped by declaring type. Within each group:
+  - Candidate function members are ordered by overload resolution priority. If the member is an override, the overload resolution priority comes from the least-derived declaration of that member.
+  - All members that have a lower overload resolution priority than the highest found within its declaring type group are removed.
+- The reduced groups are then recombined into the final set of applicable candidate function members.
 - Then, the best function member from the set of applicable candidate function members is located. If the set contains only one function member, then that function member is the best function member. Otherwise, the best function member is the one function member that is better than all other function members with respect to the given argument list, provided that each function member is compared to all other function members using the rules in [§12.6.4.3](expressions.md#12643-better-function-member). If there is not exactly one function member that is better than all other function members, then the function member invocation is ambiguous and a binding-time error occurs.
 
 The following subclauses define the exact meanings of the terms *applicable function member* and *better function member*.

standard/standard-library.md

@@ -972,6 +972,14 @@ namespace System.Runtime.CompilerServices
         public ModuleInitializerAttribute() { }
     }
 
+    [System.AttributeUsage(System.AttributeTargets.Constructor
+    | System.AttributeTargets.Method | System.AttributeTargets.Property,
+      AllowMultiple=false, Inherited=false)]
+    public sealed class OverloadResolutionPriorityAttribute : Attribute
+    {
+        public OverloadResolutionPriorityAttribute(int priority) {}
+    }
+
     [System.AttributeUsage(System.AttributeTargets.Class |
       System.AttributeTargets.Field | System.AttributeTargets.Property |
       System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)]
@@ -1553,6 +1561,7 @@ The following library types are referenced in this specification. The full names
 - `global::System.Runtime.CompilerServices.InterpolatedStringHandlerAttribute`
 - `global::System.Runtime.CompilerServices.ITuple`
 - `global::System.Runtime.CompilerServices.ModuleInitializerAttribute`
+- `global::System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute`
 - `global::System.Runtime.CompilerServices.RequiredMemberAttribute`
 - `global::System.Runtime.CompilerServices.TaskAwaiter`
 - `global::System.Runtime.CompilerServices.TaskAwaiter<TResult>`