Returning void from an Asynchronous Method

We've already looked at several valid async return types, including Task, Task<T>, ValueTask<T>, and now IAsyncEnumerable<T>, all of which support a GetAwaiter() method. There is one allowable return type (or non-type) that does not support the GetAwaiter(). This return option, which is available for an async method, is void—a method henceforth referred to as an async void method. In most cases, async void methods should be avoided and might more accurately be considered a non-option. Unlike when returning a GetAwaiter() supporting type, when there is a void return it is indeterminate when a method completes executing. If an exception occurs, returning void means there is no such container to report an exception. In such a case, any exception thrown on an async void method is likely to end up on the UI SynchronizationContext—effectively becoming an unhandled exception (see “Advanced Topic: Dealing with Unhandled Exceptions on a Thread” in Chapter 19).

If async void methods should be generally avoided, why are they allowed in the first place? It’s because async void methods can be used to enable async event handlers. As discussed in Chapter 14, an event should be declared as an EventHandler<T>, where EventHandler<T> has a signature of the following form:

void EventHandler<TEventArgs>(object sender, TEventArgs e)

Thus, to fit the convention of an event matching the EventHandler<T> signature, an async event needs to return void. One might suggest changing the convention, but (as discussed in Chapter 14) there could be multiple subscribers, and retrieving the return from multiple subscribers is nonintuitive and cumbersome. For this reason, the guideline is to avoid async void methods unless they are subscribers to an event handler—in which case they should not throw exceptions. Alternatively, you should provide a synchronization context to receive notifications of synchronization events such as the scheduling of work (e.g., Task.Run()) and, perhaps more important, unhandled exceptions. Listing 20.9 and the accompanying Output 20.2 provide an example of how to do this.

Listing 20.9: Catching an Exception from an async void Method
1. using System;
2. using System.Threading;
3. using System.Threading.Tasks;
4.  
5. public class AsyncSynchronizationContext : SynchronizationContext
6. {
7.     public Exception? Exception { get; set; }
8.     public ManualResetEventSlim ResetEvent { get; } = new();
9.  
10.     public override void Send(SendOrPostCallback callback, object? state)
11.     {
12.         try
13.         {
14.             Console.WriteLine($@"Send notification invoked...(Thread ID: {
15.                 Thread.CurrentThread.ManagedThreadId})");
16.             callback(state);
17.         }
18.         catch (Exception exception)
19.         {
20.             Exception = exception;
21.         }
22.         finally
23.         {
24.             ResetEvent.Set();
25.         }
26.     }
27.  
28.     public override void Post(SendOrPostCallback callback, object? state)
29.     {
30.         try
31.         {
32.             Console.WriteLine($@"Post notification invoked...(Thread ID: {
33.                 Thread.CurrentThread.ManagedThreadId})");
34.             callback(state);
35.         }
36.         catch (Exception exception)
37.         {
38.             Exception = exception;
39.         }
40.         finally
41.         {
42.             ResetEvent.Set();
43.         }
44.     }
45. }
46.  
47. public static class Program
48. {
49.     public static bool EventTriggered { get; set; }
50.  
51.     public const string ExpectedExceptionMessage = "Expected Exception";
52.  
53.     public static void Main()
54.     {
55.         SynchronizationContext? originalSynchronizationContext =
56.             SynchronizationContext.Current;
57.         try
58.         {
59.             AsyncSynchronizationContext synchronizationContext = new();
60.             SynchronizationContext.SetSynchronizationContext(
61.                 synchronizationContext);
62.  
63.             OnEvent(typeof(Program), EventArgs.Empty);
64.  
65.             synchronizationContext.ResetEvent.Wait();
66.  
67.             if (synchronizationContext.Exception is not null)
68.             {
69.                 Console.WriteLine($@"Throwing expected exception....(Thread ID: {
70.                 Thread.CurrentThread.ManagedThreadId})");
71.                 System.Runtime.ExceptionServices.ExceptionDispatchInfo.Capture(
72.                     synchronizationContext.Exception).Throw();
73.             }
74.         }
75.         catch (Exception exception)
76.         {
77.             Console.WriteLine($@"{exception} thrown as expected.(Thread ID: {
78.                 Thread.CurrentThread.ManagedThreadId})");
79.         }
80.         finally
81.         {
82.             SynchronizationContext.SetSynchronizationContext(
83.                 originalSynchronizationContext);
84.         }
85.     }
86.  
87.     private static async void OnEvent(object sender, EventArgs eventArgs)
88.     {
89.         Console.WriteLine($@"Invoking Task.Run...(Thread ID: {
90.                 Thread.CurrentThread.ManagedThreadId})");
91.         await Task.Run(() =>
92.         {
93.             EventTriggered = true;
94.             Console.WriteLine($@"Running task... (Thread ID: {
95.                 Thread.CurrentThread.ManagedThreadId})");
96.             throw new Exception(ExpectedExceptionMessage);
97.         });
98.     }
99. }
Output 20.2
Invoking Task.Run...(Thread ID: 8)
Running task... (Thread ID: 9)
Post notification invoked...(Thread ID: 8)
Post notification invoked...(Thread ID: 8)
Throwing expected exception....(Thread ID: 8)
System.Exception: Expected Exception
  at AddisonWesley.Michaelis.EssentialCSharp.Chapter20.Listing20_09.Program.Main() in
...Listing20.09.AsyncVoidReturn.cs:line 80 thrown as expected.(Thread ID: 8)

The code in Listing 20.9 executes procedurally up until the await Task.Run() invocation within OnEvent() starts. Following its completion, control is passed to the Post() method within AsyncSynchronizationContext. After the execution and completion of the Post() invocation, the Console.WriteLine("throw Exception...") method executes, and then an exception is thrown. This exception is captured by the AsyncSynchronizationContext.Post() method and passed back into Main().

In this example, we use a Task.Delay() call to ensure the program doesn’t end before the Task.Run() invocation. In the real world, as shown in Chapter 22, a ManualResetEventSlim would be the preferred approach.

Advanced Topic
Valid Async Return Types Expanded

Generally, the expression that follows the await keyword is of type Task, Task<T>, ValueTask<T>, occasionally void, or in C# 8.0, IAsyncEnumerable<T>/IAsyncEnumerator<string>. The word Generally, however, is a deliberate injection of incertitude. In fact, the exact rule regarding the return type that await requires is more generic than just these types. Additionally, it allows the type to be an awaitable type—supporting a GetAwaiter() method. This method produces an object that has certain properties and methods needed by the compiler’s rewriting logic—specifically, an object that supports the INotifyCompletion interface with the addition of a GetResult() method. By allowing an awaitable type, the system is extensible by third parties. In other words, if you want to design your own non-Task-based asynchrony system that uses some other type to represent asynchronous work, you can do so and still use the await syntax.

Prior to C# 8.0, it was not possible to make async methods return something other than void, Task, or Task<T> or ValueTask<T>, no matter which type is awaited inside the method. However, leveraging the more general GetAwaiter() approach, C# 8.0 introduced the IAsyncEnumerable<T>/IAsyncEnumerator<string> async return described earlier in the chapter.

{{ snackbarMessage }}
;