[Version 10.0] Feature support for async method builder attribute

standard/classes.md

@@ -422,7 +422,7 @@
     : 'where' type_parameter ':' type_parameter_constraints
     ;
 
 type_parameter_constraints
     : primary_constraint (',' secondary_constraints)? (',' constructor_constraint)?
     | secondary_constraints (',' constructor_constraint)?
     | constructor_constraint
@@ -534,15 +534,15 @@
 >     static void M()
 >     {
 >         // nonnull constraint allows nonnullable struct type argument
 >         A<int> x1;
 >         // possible warning: nonnull constraint prohibits nullable struct type argument
 >         A<int?> x2;
 >         // nonnull constraint allows nonnullable class type argument
 >         A<C> x3;
 >         // possible warning: nonnull constraint prohibits nullable class type argument
 >         A<C?> x4;
 >         // nonnullable base class requirement allows nonnullable class type argument
 >         B1<C> x5;
 >         // possible warning: nonnullable base class requirement prohibits nullable
 >         // class type argument
 >         B1<C?> x6;
@@ -3556,7 +3556,7 @@
 >     static void Main()
 >     {
 >         field = 10;
 >         Console.WriteLine(Property); // Prints 10
 >         Property = 20;               // This invokes the get accessor, then assigns
 >                                      // via the resulting variable reference
 >         Console.WriteLine(field);    // Prints 20
@@ -4917,7 +4917,7 @@
     : '!'
     ;
 
 overloadable_unary_operator
     : '+' | '-' | logical_negation_operator | '~' | '++' | '--' | 'true' | 'false'
     ;
 
@@ -5886,6 +5886,78 @@
 
 An asynchronous iterator shall support cancellation of the asynchronous operation. This is described in [§23.5.8](attributes.md#2358-the-enumeratorcancellation-attribute).
 
+Rather than using a task builder type based on the *return_type* of an async method, the attribute `AsyncMethodBuilder` can be applied to that method to indicate a different task builder type.
+
+It is an error to apply this attribute to a lambda with an implicit return type.
+
+The ability to provide an alternate builder type shall not be used when the synthesized entry-point for top-level statements is async ([§7.1.3](basic-concepts.md#713-using-top-level-statements)). For that, an explicit entry-point is needed.
+
+When an async method is compiled, the builder type is determined by:
+
+1. Using the builder type from the `AsyncMethodBuilder` attribute, if one is present;
+1. Otherwise, falling back to the builder type determined by the method’s *return_type*.
+
+If an `AsyncMethodBuilder` attribute is present, the builder type specified by that attribute is constructed, if necessary.
+
+If the override type is an open generic type, take the single type argument of the async method's return type and substitute it into the override type.
+
+If the override type is a bound generic type, then an error results.
+
+If the async method's return type does not have a single type argument, an error results.
+
+To verify that the builder type is compatible with *return_type* of the async method:
+
+1. Look for the public `Create` method with no type parameters and no parameters on the constructed builder type. It is an error if the method is not found, or if the method returns a type other than the constructed builder type.
+1. Look for the public `Task` property. It is an error if the property is not found.
+1. Consider the type of that `Task` property (a task-like type). It is an error if the task-like type does not match the *return_type* of the async method. (It is not necessary for *return_type* to be a task-like type.)
+
+Consider the following code fragment:
+
+```csharp
+public async ValueTask<T> ExampleAsync() { … }
+```
+
+This will be compiled to something like the following:
+
+```csharp
+[AsyncStateMachine(typeof(<ExampleAsync>d__29))]
+[CompilerGenerated]
+static ValueTask<int> ExampleAsync()
+{
+    <ExampleAsync>d__29 stateMachine;
+    stateMachine.<>t__builder 
+        = AsyncValueTaskMethodBuilder<int>.Create();
+    stateMachine.<>1__state = -1;
+    stateMachine.<>t__builder.Start(ref stateMachine);
+    return stateMachine.<>t__builder.Task;
+}
+```
+
+However, the following code fragment:
+
+```csharp
+[AsyncMethodBuilder(typeof(PoolingAsyncValueTaskMethodBuilder<>))]
+static async ValueTask<int> ExampleAsync() { … }
+```
+
+in which the attribute `AsyncMethodBuilder` is applied to that method, would instead be compiled to something like:
+
+```csharp
+[AsyncStateMachine(typeof(<ExampleAsync>d__29))]
+[CompilerGenerated]
+[AsyncMethodBuilder(typeof(PoolingAsyncValueTaskMethodBuilder<>))]
+static ValueTask<int> ExampleAsync()
+{
+    <ExampleAsync>d__29 stateMachine;
+    stateMachine.<>t__builder 
+        = PoolingAsyncValueTaskMethodBuilder<int>.Create();
+        // <>t__builder now a different type
+    stateMachine.<>1__state = -1;
+    stateMachine.<>t__builder.Start(ref stateMachine);
+    return stateMachine.<>t__builder.Task;
+}
+```
+
 ### 15.15.2 Enumerator interfaces
 
 The ***enumerator interface***s are the non-generic interface `System.Collections.IEnumerator` and the generic interface `System.Collections.Generic.IEnumerator<T>`.
@@ -6134,7 +6206,7 @@
 >     public static bool operator!=(R1? left, R1? right) => !(left == right);
 > 
 >     public override int GetHashCode()
 >     {
 >         return HashCode.Combine(EqualityComparer<Type>.Default.GetHashCode(EqualityContract),
 >             EqualityComparer<T1>.Default.GetHashCode(P1));
 >     }
@@ -6315,7 +6387,7 @@
 >     protected virtual bool PrintMembers(StringBuilder builder)
 >     {
 >         builder.Append(nameof(P1));
 >         builder.Append(" = ");
 >         builder.Append(this.P1); // or builder.Append(this.P1.ToString()); if P1 has a value type
 >         return true;
 >     }
@@ -6346,11 +6418,11 @@
 >             builder.Append(", ");
 >         }
 >         builder.Append(nameof(P2));
 >         builder.Append(" = ");
 >         builder.Append(this.P2); // or builder.Append(this.P2); if P2 has a value type
 >         builder.Append(", ");
 >         builder.Append(nameof(P3));
 >         builder.Append(" = ");
 >         builder.Append(this.P3); // or builder.Append(this.P3); if P3 has a value type
 >         return true;
 >     }
@@ -6484,5 +6556,5 @@
 >
 > *end example*
 
 
 

standard/standard-library.md

@@ -190,7 +190,7 @@
     public class NullReferenceException : Exception
     {
         public NullReferenceException();
         public NullReferenceException(string? message);
         public NullReferenceException(string? message, Exception? innerException);
     }
 
@@ -238,7 +238,7 @@
     public sealed class StackOverflowException : Exception
     {
         public StackOverflowException();
         public StackOverflowException(string? message);
         public StackOverflowException(string? message, Exception? innerException);
     }
 
@@ -247,7 +247,7 @@
         public int Length { get; }
         public char this [int index] { get; }
         public static string Format(string format, params object?[] args);
         System.Collections.IEnumerator IEnumerable.GetEnumerator();
         System.Collections.Generic.IEnumerator<char> IEnumerable<char>.GetEnumerator();
     }
 
@@ -407,7 +407,7 @@
     public class OperationCanceledException : Exception
     {
         public OperationCanceledException();
         public OperationCanceledException(string? message);
         public OperationCanceledException(string? message, Exception? innerException);
     }
 
@@ -680,7 +680,7 @@
     }
 
     public interface IAsyncEnumerable<out T>
     {
         IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken token = default);
     }
 
@@ -747,7 +747,7 @@
       System.AttributeTargets.Property, AllowMultiple=true, Inherited=false)]
     public sealed class MemberNotNullWhenAttribute : Attribute
     {
         public MemberNotNullWhenAttribute(bool returnValue, string member) {}
         public MemberNotNullWhenAttribute(bool returnValue, params string[] members) {}
     }
 
@@ -785,7 +785,7 @@
 namespace System.Runtime.CompilerServices
 {
     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | 
-        AttributeTargets.Interface, 
+        AttributeTargets.Interface | AttributeTargets.Method, 
         Inherited = false, AllowMultiple = false)]
     public sealed class AsyncMethodBuilderAttribute : Attribute
     {