Peter Ritchie's MVP Blog : C# 5

async/await Tips

PeterRitchie — Wed, 13 Feb 2013 18:02:21 GMT

There’s been some really good guidance about async/await in the past week or two. I’ve been tinkering away at this post for a while now—based on presentations I’ve been doing, discussions I’ve had with folks at Microsoft, etc. Now seems like a good idea to post it.

First, it’s important to understand what the "async" keyword really mean. At face value async doesn’t make a method (anonymous or member) “asynchronous”—the body of the method does that. What it does mean is that there’s a strong possibility that the body of the method won’t entirely be evaluated when the method returns to the caller. i.e. it “might” be asynchronous. What the compiler does is create a state machine that manages the various “awaits” that occur within an async method to manage the results and invoking continuations when results are available. I’m not going to get into too much detail about the state machine, other than to say the entry to the method is now the creation of that state machine and the initialization of moving from state to state (much like the creation of an enumerable and moving from one element—the state—to the next). The important part to remember here is that when an async method returns, there can be some code that will be evaluated in the future.

If you’ve ever done any work with HttpWebRequest and working with responses (e.g. disposal), you’ll appreciate being able to do this:

Parallelism

await is great to declare asynchronous operations in a sequential way. This allows you to use other sequential syntax like using and try/catch to deal with common .NET axioms in the axiomatic way. await, in my opinion, is really about allowing user interfaces to support asynchronous operations in an easy way with intuitive code. But, you can also use await to wait for parallel operations to complete. For example, on a two core computer I can start up two tasks in parallel then await on both of them (one at a time) to complete:

If you run this code you should see the elapsed values (on a two or more core/cpu computer) will be very similar (not 1 second apart). Contrast the subtle differences to:

While you can use await with parallel operations, the subtlety in the differences between sequential asynchronous operations can lead to incorrect code due to misunderstandings. I suggest paying close attention to how you structure your code so it is in fact doing what you expect it to do. In most cases, I simply recommend not doing anything “parallel” with await.

async void

The overwhelming recommendation is to avoid async methods that return void. Caveat: the reason async void was made possible by the language teams was the fact that most event handlers return void; but it is sometimes useful for an event handler to be asynchronous (e.g. await another asynchronous method). If you want to have a method that uses await but doesn’t return anything (e.g. would otherwise be void) you can simply change the void to Task. e.g.:

This tells the compiler that the method doesn’t asynchronously return a value, but can now be awaited:

Main

Main can't be async. As we described above an async method can return with code that will be evaluated in the future Main returns, the application exits. If you *could* have an async Main, it would be similar to doing this:

This, depending on the platform, the hardware, and the current load, would mean that the Console.WriteLine *might* get executed.

Fortunately, this is easily fixed by creating a new method (that can be modified with async) then call it from Main.

Exceptions

One of the biggest advantages of async/await is the ability to write sequential code with multiple asynchronous operations. Previously this required methods for each continuation (actual methods prior to .NET 2.0 and anonymous methods and lambdas in .NET 2.0 and .NET 3.5). Having code span multiple methods (whether they be anonymous or not) meant we couldn’t use axiomatic patterns like try/catch (not to mention using) very effectively—we’d have to check for exceptions in multiple places for the same reason.

There are some subtle ways exceptions can flow back from async methods, but fortunately the sequential nature of programming with await, you may not care. But, with most things, it' depends. Most of the time exceptions are caught in the continuation. This usually means on a thread different from the main (UI) thread. So, you have to be careful what you do when you process the exception. For example, given the following two methods.

And if we wrapped calls to each in try/catch:

In the first case (calling DoSomething1) the exception is caught on the same thread that called Start (i.e. before the await occurred). *But*, in the second case (calling DoSomething2) the exception is not caught on the same thread as the caller. So, if you wanted to present information via the UI then you’d have to check to see if you’re on the right thread to display information on the UI (i.e. marshal back to the UI thread, if needed).

Of course, any method can throw exceptions in the any of the places of the above two methods, so if you need to do something with thread affinity (like work with the UI) you’ll have to check to see if you need to marshal back to the UI thread (Control.BeginInvoke or Dispatcher.Invoke).

Unit testing

Unit testing asynchronous code can get a bit hairy. For the most part, testing asynchronously is really just testing the compiler and runtime—not something that is recommended (i.e. it doesn’t buy you anything, it’s not your code). So, for the most part, I recommend people test the units they intend to test. e.g. test synchronous code. For example, I could write an asynchronous method that calculates Pi as follows:

…which is fairly typical. Asynchronous code is often the act of running something on a background thread/task. I *could* then write a test for this that executes code like this:

But, what I really want to test is that Pi is calculated correctly, not that it occurred asynchronously. In certain circumstances something may *not* executed asynchronously anyway. So, I generally recommend in cases like this the test actually be:

Of course, that may not always be possible. You may only have an asynchronous way of invoking code, and if you can’t decompose into asynchronous and synchronous parts for testability then using await is likely the easiest option. But, there’s some things to watch out for. When writing a test for this asynchronous method you might intuitively write something like this:

But, the problem with this method is that the Assert may not occur before the test runner exits. This method doesn’t tell the runner that it should wait for a result. It’s effectively async void (another area not to use it). This can easily be fixed by changing the return from void to Task:

A *very* subtle change; but this lets the runner know that the test method is “awaitable” and that it should wait for the Task to complete before exiting the runner. Apparently many test runners recognize this and act accordingly so that your tests will actually run and your asynchronous code will be tested.

Testing Strategies Involving Async Functions

PeterRitchie — Thu, 04 Nov 2010 16:26:00 GMT

Some things to keep in mind when writing units tests for code that use async methods: You're not trying to test the framework's "awaitability" and you're not trying to test framework methods that are "awaitable". You want to test your code in certain isolation contexts. One context, of course, is independent of asynchronicity--do individual units of code that don't depend on asynchronous invocation "work"... e.g. "Task<string> MyMethodAsync()", you want to have a unit test that make sure this method does what it's supposed to do (one being it returns a "valid" Task<string> object, the other being that individual side-effects occur, if any). Another context is dependent on asynchronicity--do individual units of code that do depend on asynchronous invocation (or depend on something being invoked asynchronously) "work".

It's the second context that seems to be the hardest to grasp for most people to grasp and action. Let's take this example code:

	private async void startButton_Click(object sender, EventArgs e)
	{
		try
		{
			startButton.Enabled = false;
			var webRequest = WebRequest.Create("http://google.ca");
			using (var response = await webRequest.GetResponseAsync())
			using (var stream = response.GetResponseStream())
			{
				if (stream == null) return;
				using (var reader = new StreamReader(stream))
				{
					textBox.Text = await reader.ReadToEndAsync();
				}
			}
		}
		finally
		{
			startButton.Enabled = true;
		}
	}

A couple invariants that we want to test might be that the button is disabled during the asynchronous operations and enabled after the asynchronous operations. It's not immediately obvious what to in order to validate these invariants.

When the compiler encounters the await operator, it actually goes searching for method that can act upon the type of the object being returned by the method used with the await operator. In our first use of await (on GetResponseAsync()) the return type is Task<T> (Task<WebResponse> specifically, but for our example I'll use Task<T>). There's various criteria the computer uses to search for this method, one method is to search for extension methods that match the name and return an "awaiter" type that has the following methods: BeginAwait and EndAwait (more details can be found in the Aync CTP documentation). The compiler doesn't allow us to inject an awaiter type in the normal run-time dependency injection semantics; but it does allow us to implement an awaiter that does support dependency injection at run-time. To do this I would create an ITaskAwaiter interface like this:

	public interface ITaskAwaiter<out T>
	{
		bool BeginAwait(Action continuation);
		T EndAwait();
	}

I then need to create a GetAwaiter(this Task<T>) extension method to return an implementation of this type. The built-in System.Runtime.CompilerServices.TaskAwaiter<T> is public; but, unfortunately it's constructor (and the ability to pass in a Task<T>) object is internal. So, we can't simply wrap the built-in awaiter and delegate to it as a default. We actually have to write an awaiter that mimics what the built-in one does. For example:

	public class TaskAwaiter<T> : ITaskAwaiter<T>
	{
		private readonly Task<T> task;
 
		public TaskAwaiter(Task<T> task)
		{
			this.task = task;
		}
 
		public bool BeginAwait(Action continuation)
		{
			if (task.IsCompleted) return false;
			var synchronizationContext = SynchronizationContext.Current;
			Action<Task> action = theTask => 
			                      	{
			                      		if (synchronizationContext != null)
			                      		{
			                      			synchronizationContext.Post(state => continuation(), null);
			                      		}
			                      		else
			                      		{
			                      			continuation();
			                      		}
			                      	};
 
			task.ContinueWith(action, CancellationToken.None, TaskContinuationOptions.ExecuteSynchronously, TaskScheduler.Current);
			return true;
		}
 
		public T EndAwait()
		{
			return task.Result;
		}
	}

This class is given the Task<T> in question, it implements a BeginWait method that sets up an Action delegate to invoke the continuation given to it in a specific synchronization context, then tells the task to use that new action as it's continuation via a call to ContinueWith. When the task is completed EndAwait will be called and we simply return the result of the task.

Now, in order to add the ability to inject a customer awaiter, we need to provide the GetAwaiter extension method. For example:

	namespace PRI.Extensions
	{
		static class TaskExtensions
		{
			static public ITaskAwaiter<TResult> GetAwaiter<TResult>(this Task<TResult> task)
			{
				return TaskAwaiterFactory<TResult>.CreateTaskAwaiter != null
					? TaskAwaiterFactory<TResult>.CreateTaskAwaiter(task) : new TaskAwaiter<TResult>(task);
			}
		}
	}

This extension method invokes a factory method delegate to create the ITaskAwaiter<T> object (or simply creates our new default awaiter). This factory method looks like this:

	internal static class TaskAwaiterFactory<TResult>
	{
		private static Func<Task<TResult>, ITaskAwaiter<TResult>> createTaskAwaiter = task =>
		                                                                              	{
		                                                                              		Current = new TaskAwaiter<TResult>(task);
		                                                                              		return Current;
		                                                                              	};
		public static Func<Task<TResult>, ITaskAwaiter<TResult>> CreateTaskAwaiter
		{
			get { return createTaskAwaiter; }
			set
			{
				createTaskAwaiter = task =>
				                    	{
				                    		Current = value(task);
				                    		return Current;
				                    	};
			}
		}
		public static ITaskAwaiter<TResult> Current { get; private set; }
	}

We can override this factory method and give a delegate to code that creates another type of ITaskAwaiter<T> implementation. We also decorate the call to that provided delegate with something that keeps track of the Current awaiter (more on that later). Now, we simply need to add a using statement within our namespace for the compiler to user our GetAwaiter when it compiles an await operator and use our factory. For example:

	namespace PRI.MainApplication
	{
		using PRI.Extensions;
 
		//...

We're now all set to inject a new awaiter and be able to isolate our code from the framework and validate some invariants. In our case, we'd like to check to make sure that the button is disabled during invocation of asynchronous operations and enabled when done. So, we can create a spy awaiter that basically does nothing and sends back a fake or dummy object. In our example we actually have two different types of Task<T> objects being awaited; so, we need to create a couple of awaiter spys. One is generic and one is specific. For example:

	public class WebResponseTaskAwaiterSpy : ITaskAwaiter<WebResponse>
	{
		private class FakeWebResponse : WebResponse
		{
			public override Stream GetResponseStream()
			{
				return new MemoryStream(System.Text.Encoding.ASCII.GetBytes("got some text"));
			}
		}
		private readonly MainForm form;
		public bool ButtonEnabledState { get; private set; }
		public WebResponseTaskAwaiterSpy(MainForm form)
		{
			this.form = form;
		}
 
		public bool BeginAwait(Action continuation)
		{
			return false;
		}
 
		public WebResponse EndAwait()
		{
			ButtonEnabledState = form.startButton.Enabled;
			return new FakeWebResponse();
		}
	}
 
	public class TaskAwaiterSpy<T> : ITaskAwaiter<T>
	{
		private readonly MainForm form;
		public bool ButtonEnabledState { get; private set; }
		public TaskAwaiterSpy(MainForm form)
		{
			this.form = form;
		}
 
		public bool BeginAwait(Action continuation)
		{
			return false;
		}
 
		public T EndAwait()
		{
			ButtonEnabledState = form.startButton.Enabled;
			return default(T);
		}
	}

Both classes don't actually execute the task because we know task execution works and we know it works asynchronously--we're not trying to test that. The clases return false from BeginAwait to tell the generated code that the asynchronous code "completed" (we lie). The generated code the calls the EndAwait method to get the result of the so-called asynchronous operation. In both cases, we get the state of the button in EndAwait. In the case of the generic spy, we simply return a dummy--the default value for that type parameter. In the case of the WebResponse spy, we can't send back a dummy because that would be a null value and we'd get NullReferenceEexceptions that would abort our test. So, we create a FakeWebResponse object and send that back that basically creates a canned response stream in memory and sends it back and that will be used in our second await.

Now, we can write a unit test for startButton_Click method. For example:

	MainForm form = CreateForm();
	TaskAwaiterFactory<WebResponse>.CreateTaskAwaiter = task => new WebResponseTaskAwaiterSpy(form);
	TaskAwaiterFactory<String>.CreateTaskAwaiter = task => new TaskAwaiterSpy<String>(form);
 
	form.startButton_Click(null, EventArgs.Empty);
 
	var spy1 = TaskAwaiterFactory<WebResponse>.Current as WebResponseTaskAwaiterSpy;
	var spy2 = TaskAwaiterFactory<String>.Current as TaskAwaiterSpy<String>;
 
	Assert.IsTrue((spy2 != null && !spy2.ButtonEnabledState) && (spy1 != null && !spy1.ButtonEnabledState));
	Assert.IsTrue(form.startButton.Enabled);

This code injects our two types of awaiters (our spies), invokes the method, then checks the spies for the values we're looking for as well as the current state of our button (we assume the current state at this point is the same state immediately after the asynchronous operation completed) to validate our invariants.

More on Async Functions

PeterRitchie — Fri, 29 Oct 2010 20:12:00 GMT

In my last post I showed .Net 1.1 and .NET 2.0 code that performed some asychronous operations. I then showed the new syntax with "async" and "await" that did the same thing.

But, I didn't detail what's really going on in the new syntax.

If you want to know more about the details of what's going on, read on. If you just trust me about the previous code, you don't have to read on :)

When the Click handler is executed it basically executes everything up to the first await and returns. This allows the UI to be responsive. The compiler generates some code that takes the Task<T> object that is returned from the async method and waits for it. If there is code that needs to execute after the await, then the compiler effectively generates a continuation. With regard to Task<T>, that's basically a call to Task<T>.ContinueWith. Any other await statements are collected in that continuation and the same thing is done, the continuation is executed up to the first await and returns...

The underlying architecture knows about synchronization contexts and makes sure "synchronous" code within the Click handler is executed on the UI thread. So, as you saw in the example, we didn't have to manually deal with marshaling back to the UI thread via Control.Invoke().

My original example was overly simplistic and didn't include anything to deal with disposal. To a certain extent I've done async functions a disservice because async functions make disposal much, much easier. For example, my .NET 4.0 code would do something like this:

private void button_Click(object sender, EventArgs e)
{
button.Enabled = false;
var webRequest = WebRequest.Create("http://google.ca");
webRequest.BeginGetResponse(asyncResult =>
{
  var response = webRequest.EndGetResponse(asyncResult);
  var stream = response.GetResponseStream();
  if (stream != null)
  {
   var reader = new StreamReader(stream);
   var text = reader.ReadToEnd();
   BeginInvoke((MethodInvoker) (() =>
   {
    textBox.Text = text;
    button.Enabled = true;
    reader.Dispose();
    stream.Dispose();
    ((IDisposable) response).Dispose();
   }));
  }
  else
  {
   ((IDisposable)response).Dispose();
  }
}, null);
}

As you can see, we can't use the using statement because that assumes the block in which using block resides is run asynchronously, so we're forced to manually call Dispose (and in the case of WebResponse, cast to IDisposable first because it explicitly implements IDisposable).

With await, we can write a block of code with bits of it being asynchronous and still use using statements. So, with async functions, our code can now dispose more cleanly; for example:

private async void button1_Click(object sender, EventArgs e)
{
try
{
  button.Enabled = false;
  var webRequest = WebRequest.Create("http://google.ca");
  using (var response = await webRequest.GetResponseAsync())
  using (var stream = response.GetResponseStream())
  {
   if (stream == null) return;
   using (var reader = new StreamReader(stream))
   {
    textBox.Text = await reader.ReadToEndAsync();
   }
  }
}
finally
{
  button.Enabled = true;
}
}

C# 3 and lambda expressions make the act of using asynchronous methods much easier than .NET 1.x; the next version of C# with async functions takes it that final step forward.