Using coroutines in Unity is often a great way to solve certain problems, however it comes with certain drawbacks as well:
- Coroutines can’t return values. This encourages programmers to create huge monolithic coroutine methods instead of composing them out of many smaller methods. Some workarounds exist, such as passing a callback parameter of type Action<> to the coroutine, or casting the final untyped value that is yielded from the coroutine after it completes, but these approaches are awkward to use and error prone.
- Coroutines make error handling difficult. You cannot put a yield inside a try-catch, so it is not possible to handle exceptions. Also, when exceptions do occur the stack trace only tells you the coroutine where the exception was thrown, so you have to guess which other coroutines it might have been called from.
With the release of Unity 2017, it is now possible to use a new C# feature called async-await for our asynchronous methods instead. This comes with a lot of nice features compared to coroutines.
To enable this feature, all you need to do is open your player settings (Edit -> Project Settings -> Player) and change “Scripting Runtime Version” to “Experimental (.NET 4.6 Equivalent).
Let’s look at a simple example. Given the following coroutine:
1 2 3 4 5 6 7 8 9 | public class AsyncExample : MonoBehaviour
{
IEnumerator Start()
{
Debug.Log("Waiting 1 second...");
yield return new WaitForSeconds(1.0f);
Debug.Log("Done!");
}
}
|
The equivalent way to do this using async-await would be the following:
1 2 3 4 5 6 7 8 9 | public class AsyncExample : MonoBehaviour
{
async void Start()
{
Debug.Log("Waiting 1 second...");
await Task.Delay(TimeSpan.FromSeconds(1));
Debug.Log("Done!");
}
}
|
It’s helpful to be somewhat aware of what’s happening under-the-hood in both these cases.
In short, Unity coroutines are implemented using C#’s built-in support for iterator blocks. The IEnumerator iterator object that you provide to the StartCoroutine method is saved by Unity and each frame this iterator object is advanced forward to get new values that are yielded by your coroutine. The different values that you ‘yield return’ are then read by Unity to trigger special case behaviour, like executing a nested coroutine (when returning another IEnumerator), delaying by some number of seconds (when returning an instance of type WaitForSeconds), or just waiting until the next frame (when returning null).
Unfortunately, due to the fact that async-await is quite new within Unity, this built-in support for coroutines as explained above does not exist in a similar fashion for async-await. Which means that we have to add a lot of this support ourselves.
Unity does provide one important piece for us however. As you can see in the above example, our async methods will be run on the main unity thread by default. In non-unity C# applications, async methods are often automatically run on separate threads, which would be a big problem in Unity since we would not always be able to interact with the Unity API in these cases. Without this support from the Unity engine, our calls to Unity methods/objects inside our async methods would sometimes fail because they would be executed on a separate thread. Under the hood it works this way because Unity has provided a default SynchronizationContext called UnitySynchronizationContext which automatically collects any async code that is queued each frame and continues running them on the main unity thread.
As it turns out, however, this is enough to get us started with using async-await! We just need a bit of helper code to allow us to do some more interesting things than just simple time delays.
Custom Awaiters
Currently, there’s not a lot of interesting async code we can write. We can call other async methods, and we can use Task.Delay, like in the example above, but not much else.
As a simple example, let’s add the ability to directly ‘await’ on a TimeSpan instead of always having to call Task.Delay every time like the example above. Like this:
1 2 3 4 5 6 7 | public class AsyncExample : MonoBehaviour
{
async void Start()
{
await TimeSpan.FromSeconds(1);
}
}
|
All we need to do to support this is to simply add a custom GetAwaiter extension method to the TimeSpan class:
1 2 3 4 5 6 7 | public static class AwaitExtensions
{
public static TaskAwaiter GetAwaiter(this TimeSpan timeSpan)
{
return Task.Delay(timeSpan).GetAwaiter();
}
}
|
This works because in order to support ‘awaiting’ a given object in newer versions of C#, all that’s needed is that the object has a method named GetAwaiter that returns an Awaiter object. This is great because it allows us to await anything we want, by using an extension method like above, without needing to change the actual TimeSpan class.
We can use this same approach to support awaiting other types of objects too, including all of the classes that Unity uses for coroutine instructions! We can make WaitForSeconds, WaitForFixedUpdate, WWW, etc all awaitable in the same way that they are yieldable within coroutines. We can also add a GetAwaiter method to IEnumerator to support awaiting coroutines to allow interchanging async code with old IEnumerator code.
The code to make all this happen can be downloaded from either asset store or the releases section of the github repo. This allows you to do things like the following:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | public class AsyncExample : MonoBehaviour
{
public async void Start()
{
await new WaitForSeconds(1.0f);
await CustomCoroutineAsync();
await LoadModelAsync();
var value = (string)(await CustomCoroutineWithReturnValue());
var returnCode = await Process.Start("notepad.exe");
await SceneManager.LoadSceneAsync("scene2");
}
async Task LoadModelAsync()
{
var assetBundle = await GetAssetBundle("www.my-server.com/myfile");
var prefab = await assetBundle.LoadAssetAsync<GameObject>("myasset");
GameObject.Instantiate(prefab);
assetBundle.Unload(false);
}
async Task<AssetBundle> GetAssetBundle(string url)
{
return (await new WWW(url)).assetBundle
}
IEnumerator CustomCoroutineAsync()
{
yield return new WaitForSeconds(1.0f);
}
IEnumerator CustomCoroutineWithReturnValue()
{
yield return new WaitForSeconds(1.0f);
yield return "asdf";
}
}
|
As you can see, using async await like this can be very powerful, especially when you start composing multiple async methods together like in the LoadModelAsync method above.
Note that for async methods that return values, we use the generic version of Task and pass our return type as the generic argument like with the GetAssetBundle above.
Note also that using WaitForSeconds above is actually preferable to our TimeSpan extension method in most cases because WaitForSeconds will use the Unity game time whereas our TimeSpan extension method will always use real time (so it would not be affected by changes to Time.timeScale)
Triggering Async Code and Exception Handling
One thing you might have noticed with our code above is that some methods are defined ‘async void’ and some are defined ‘async Task’. So when should you use one over the other?
The main difference here is that methods that are defined ‘async void’ cannot be waited on by other async methods. This would suggest that we should always prefer to define our async methods with return type Task so that we can ‘await’ on them.
The only exception to this rule is when you want to call an async method from non-async code. Take the following example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | public class AsyncExample : MonoBehaviour
{
public void OnGUI()
{
if (GUI.Button(new Rect(100, 100, 100, 100), "Start Task"))
{
RunTaskAsync();
}
}
async Task RunTaskAsync()
{
Debug.Log("Started task...");
await new WaitForSeconds(1.0f);
throw new Exception();
}
}
|
In this example, when the user clicks the button, we want to start our async method. This code will compile and run, however there is a major issue with it. If any exceptions occur within the RunTaskAsync method, they will happen silently. The exception will not be logged to the unity console.
This is because when exceptions occur in async methods returning Task, they are captured by the returned Task object instead of being thrown and handled by Unity. This behaviour exists for a good reason: To allow async code to work properly with try-catch blocks. Take the following code for example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | async Task DoSomethingAsync()
{
var task = DoSomethingElseAsync();
try
{
await task;
}
catch (Exception e)
{
}
}
async Task DoSomethingElseAsync()
{
throw new Exception();
}
|
Here, the exception is captured by the Task returned by the DoSomethingElseAsync method and is only re-thrown when it is ‘awaited’. As you can see, invoking async methods is distinct from awaiting on them, which is why it’s necessary to have the Task object capture the exceptions.
So in our OnGUI example above, when the exception is thrown inside the RunTaskAsync method, it is captured by the returned Task object, and since nothing awaits on this Task, the exception does not get bubbled up to Unity and therefore is never logged to the console.
But that leaves us with the question of what to do in these cases where we want to call async methods from non-async code. In our example above, we want to start the RunTaskAsync async method from inside the OnGUI method and we don’t care about waiting for it to complete, so we don’t want to have to add an await just so that exceptions can be logged.
The rule of thumb to remember here is:
Never call `async Task` methods without also awaiting on the returned Task. If you don’t want to wait for the async behaviour to complete, you should call an `async void` method instead.
So our example becomes:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | public class AsyncExample : MonoBehaviour
{
public void OnGUI()
{
if (GUI.Button(new Rect(100, 100, 100, 100), "Start Task"))
{
RunTask();
}
}
async void RunTask()
{
await RunTaskAsync();
}
async Task RunTaskAsync()
{
Debug.Log("Started task...");
await new WaitForSeconds(1.0f);
throw new Exception();
}
}
|
If you run this code again, you should now see that the exception is logged. This is because when the exception gets thrown during the await in the RunTask method, it bubbles up to Unity and gets logged to the console, because in that case there is no Task object to capture it instead.
Methods that are marked as `async void` represent the root level ‘entry point’ for some async behaviour. A good way to think about them is that they are ‘fire and forget’ tasks that go off and execute some number of things in the background while any calling code immediately continues on.
By the way, this is also a good reason to follow the convention of always using the suffix ‘Async’ on async methods that return Task. This is standard practice in most code bases that use async-await. It is helpful in conveying the fact that the method should always be preceded by an ‘await’, but also allows you to create an `async void` counterpart for the method that does not include the suffix.
Also worth mentioning is that if you are compiling your code in visual studio, then you should receive warnings when you attempt to call an `async Task` method without an associated await, which is a great way to avoid this mistake.
As an alternative to creating your own ‘async void’ method, you can also use a helper method (included with the source code associated with this article) that will perform the await for you. In this case our example would become:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | public class AsyncExample : MonoBehaviour
{
public void OnGUI()
{
if (GUI.Button(new Rect(100, 100, 100, 100), "Start Task"))
{
RunTaskAsync().WrapErrors();
}
}
async Task RunTaskAsync()
{
Debug.Log("Started task...");
await new WaitForSeconds(1.0f);
throw new Exception();
}
}
|
The WrapErrors() method is simply a generic way to ensure that the Task gets awaited on, so that Unity will always receive any exceptions that are thrown. It simply does an await and that’s it:
1 2 3 4 | public static async void WrapErrors(this Task task)
{
await task;
}
|
Calling async from coroutines
For some code bases, migrating away from coroutines to use async-await might seem like a daunting task. We can make this process simpler by allowing async-await to be adopted incrementally. In order to do this however, we not only need the ability to call IEnumerator code from async code but we also need to be able to call async code from IEnumerator code. Thankfully, we can add this very easily with yet another extension method:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | public static class TaskExtensions
{
public static IEnumerator AsIEnumerator(this Task task)
{
while (!task.IsCompleted)
{
yield return null;
}
if (task.IsFaulted)
{
throw task.Exception;
}
}
}
|
Now we can call async methods from coroutines like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | public class AsyncExample : MonoBehaviour
{
public void Start()
{
StartCoroutine(RunTask());
}
IEnumerator RunTask()
{
yield return RunTaskAsync().AsIEnumerator();
}
async Task RunTaskAsync()
{
}
}
|
Multiple Threads
We can also use async-await to execute multiple threads. You can do this in two ways. The first way is to use the ConfigureAwait method like this:
1 2 3 4 5 6 7 8 9 10 11 12 | public class AsyncExample : MonoBehaviour
{
async void Start()
{
await Task.Delay(TimeSpan.FromSeconds(1.0f)).ConfigureAwait(false);
}
}
|
As mentioned above, Unity provides something called a default SynchronizationContext, which will execute asynchronous code on the main Unity thread by default. The ConfigureAwait method allows us to override this behaviour, and so the result will be that the code below the await will no longer be guaranteed to run on the main Unity thread and will instead inherit the context from the task that we are executing, which in some cases might be what we want.
If you want to explicitly execute code on a background thread, you can also do this:
1 2 3 4 5 6 7 8 9 10 11 12 | public class AsyncExample : MonoBehaviour
{
async void Start()
{
await new WaitForBackgroundThread();
}
}
|
WaitForBackgroundThread is a class included in the source code for this post, and will do the work of starting a new thread and also ensuring that Unity’s default SynchronizationContext behaviour is overridden.
What about returning to the Unity thread?
You can do this simply by awaiting any of the Unity specific objects that we created above. For example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | public class AsyncExample : MonoBehaviour
{
async void Start()
{
await new WaitForBackgroundThread();
await new WaitForSeconds(1.0f);
}
}
|
The included source code also provides a class WaitForUpdate() that you can use if you just want to return to the unity thread without any delay:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | public class AsyncExample : MonoBehaviour
{
async void Start()
{
await new WaitForBackgroundThread();
await new WaitForUpdate();
}
}
|
Of course, if you do use background threads, you need to be very careful to avoid concurrency issues. However it can be worth it in a lot of cases to improve performance.
Gotchas and Best Practices
- Avoid async void in favour of async Task, except in ‘fire and forget’ cases where you want to start async code from non-async code
- Attach the suffix ‘Async’ to all async methods which return Task. This is helpful in conveying the fact that it should always be preceded by an ‘await’ and allows an async void counterpart to be added easily without conflict
- Debugging async methods using breakpoints in visual studio doesn’t work yet. However the “VS tools for Unity” team says that they are working on it, as indicated here
UniRx
Yet another way to do asynchronous logic is to use reactive programming with a library like UniRx. Personally I am a huge fan of this type of coding and use it extensively in many projects that I’m involved with. And thankfully, it is very easy to use alongside async-await with just another custom awaiter. For example:
1 2 3 4 5 6 7 8 9 10 | public class AsyncExample : MonoBehaviour
{
public Button TestButton;
async void Start()
{
await TestButton.OnClickAsObservable();
Debug.Log("Clicked Button!");
}
}
|
I find that UniRx observables serve a different purpose from long-running async methods/coroutines, so they naturally fit alongside a workflow using async-await like in the examples above. I won’t go into detail here, because UniRx and reactive programming is a separate topic in itself, but I will say that once you get comfortable thinking about data flow in your application in terms of UniRx “streams”, there is no going back.
Source Code
You can download the source code that includes async-await support from either asset store or the releases section of the github repo.
Further Reading
[출처] http://www.stevevermeulen.com/index.php/2017/09/using-async-await-in-unity3d-2017/
BigInteger.zip