[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'
     ;
 
@@ -5872,6 +5872,80 @@
 
 This allows the context to keep track of how many `void`-returning async functions are running under it, and to decide how to propagate exceptions coming out of them.
 
+Rather than using a task builder type based on the *return_type* of an async function, the attribute `AsyncMethodBuilder` can be applied to that async function 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). For that, an explicit entry-point is needed.
+
+When an async function 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 async function's *return_type* (§15.14.2).
+
+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 function'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 function'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 function:
+
+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 function. (It is not necessary for *return_type* to be a task-like type.)
+
+> *Example*: Consider the following code fragment:
+>
+> ```csharp
+> public async ValueTask<int> 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 async function, 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;
+> }
+> ```
+>
+> *end example*
+
 ## 15.15 Synchronous and asynchronous iterators
 
 ### 15.15.1 General
@@ -6134,7 +6208,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 +6389,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 +6420,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 +6558,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);
     }
 
@@ -675,7 +675,7 @@
     }
 
     public interface IAsyncEnumerable<out T>
     {
         IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken token = default);
     }
 
@@ -742,7 +742,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) {}
     }
 
@@ -780,7 +780,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
     {
@@ -898,7 +898,7 @@
     }
 
     public class Task<TResult> : Task
     {
         public new System.Runtime.CompilerServices.TaskAwaiter<TResult> GetAwaiter();
     }