Async Task Types in C#
Async Task Types in C#
Extend async
to support task types that match a specific pattern, in addition to the well known types System.Threading.Tasks.Task
and System.Threading.Tasks.Task<T>
.
Task Type
A task type is a class
or struct
with an associated builder type identified with System.Runtime.CompilerServices.AsyncMethodBuilderAttribute
. The task type may be non-generic, for async methods that do not return a value, or generic, for methods that return a value.
To support await
, the task type must have a corresponding, accessible GetAwaiter()
method that returns an instance of an awaiter type (see C# 7.7.7.1 Awaitable expressions).
[AsyncMethodBuilder(typeof(MyTaskMethodBuilder<>))]
class MyTask<T>
{
public Awaiter<T> GetAwaiter();
}
class Awaiter<T> : INotifyCompletion
{
public bool IsCompleted { get; }
public T GetResult();
public void OnCompleted(Action completion);
}
Builder Type
The builder type is a class
or struct
that corresponds to the specific task type. The builder type has the following public
methods. For non-generic builder types, SetResult()
has no parameters.
class MyTaskMethodBuilder<T>
{
public static MyTaskMethodBuilder<T> Create();
public void Start<TStateMachine>(ref TStateMachine stateMachine)
where TStateMachine : IAsyncStateMachine;
public void SetStateMachine(IAsyncStateMachine stateMachine);
public void SetException(Exception exception);
public void SetResult(T result);
public void AwaitOnCompleted<TAwaiter, TStateMachine>(
ref TAwaiter awaiter, ref TStateMachine stateMachine)
where TAwaiter : INotifyCompletion
where TStateMachine : IAsyncStateMachine;
public void AwaitUnsafeOnCompleted<TAwaiter, TStateMachine>(
ref TAwaiter awaiter, ref TStateMachine stateMachine)
where TAwaiter : ICriticalNotifyCompletion
where TStateMachine : IAsyncStateMachine;
public MyTask<T> Task { get; }
}
Execution
The types above are used by the compiler to generate the code for the state machine of an async
method. (The generated code is equivalent to the code generated for async methods that return Task
, Task<T>
, or void
. The difference is, for those well known types, the builder types are also known to the compiler.)
Builder.Create()
is invoked to create an instance of the builder type.
If the state machine is implemented as a struct
, then builder.SetStateMachine(stateMachine)
is called with a boxed instance of the state machine that the builder can cache if necessary.
builder.Start(ref stateMachine)
is invoked to associate the builder with compiler-generated state machine instance. The builder must call stateMachine.MoveNext()
either in Start()
or after Start()
has returned to advance the state machine. After Start()
returns, the async
method calls builder.Task
for the task to return from the async method.
Each call to stateMachine.MoveNext()
will advance the state machine. If the state machine completes successfully, builder.SetResult()
is called, with the method return value if any. If an exception is thrown in the state machine, builder.SetException(exception)
is called.
If the state machine reaches an await expr
expression, expr.GetAwaiter()
is invoked. If the awaiter implements ICriticalNotifyCompletion
and IsCompleted
is false, the state machine invokes builder.AwaitUnsafeOnCompleted(ref awaiter, ref stateMachine)
. AwaitUnsafeOnCompleted()
should call awaiter.OnCompleted(action)
with an action that calls stateMachine.MoveNext()
when the awaiter completes. Similarly for INotifyCompletion
and builder.AwaitOnCompleted()
.
Overload Resolution
Overload resolution is extended to recognize task types in addition to Task
and Task<T>
.
An async
lambda with no return value is an exact match for an overload candidate parameter of non-generic task type, and an async
lambda with return type T
is an exact match for an overload candidate parameter of generic task type.
Otherwise if an async
lambda is not an exact match for either of two candidate parameters of task types, or an exact match for both, and there is an implicit conversion from one candidate type to the other, the from candidate wins. Otherwise recursively evaluate the types A
and B
within Task1<A>
and Task2<B>
for better match.
Otherwise if an async
lambda is not an exact match for either of two candidate parameters of task types, but one candidate is a more specialized type than the other, the more specialized candidate wins.