UniTask

Provides an efficient allocation free async/await integration for Unity.

• Struct based UniTask<T> and custom AsyncMethodBuilder to achieve zero allocation
• Makes all Unity AsyncOperations and Coroutines awaitable
• PlayerLoop based task(UniTask.Yield, UniTask.Delay, UniTask.DelayFrame, etc..) that enable replacing all coroutine operations
• MonoBehaviour Message Events and uGUI Events as awaitable/async-enumerable
• Runs completely on Unity's PlayerLoop so doesn't use threads and runs on WebGL, wasm, etc.
• Asynchronous LINQ, with Channel and AsyncReactiveProperty
• TaskTracker window to prevent memory leaks
• Highly compatible behaviour with Task/ValueTask/IValueTaskSource

For technical details, see blog post: UniTask v2 — Zero Allocation async/await for Unity, with Asynchronous LINQ
For advanced tips, see blog post: Extends UnityWebRequest via async decorator pattern — Advanced Techniques of UniTask

Table of Contents

• Getting started
• Basics of UniTask and AsyncOperation
• Cancellation and Exception handling
• Timeout handling
• Progress
• PlayerLoop
• async void vs async UniTaskVoid
• UniTaskTracker
• External Assets
• AsyncEnumerable and Async LINQ
• Awaitable Events
• Channel
• For Unit Testing
• ThreadPool limitation
• IEnumerator.ToUniTask limitation
• For UnityEditor
• Compare with Standard Task API
• Pooling Configuration
• Allocation on Profiler
• UniTaskSynchronizationContext
• API References
• UPM Package
  • Install via git URL
• .NET Core
• License

Getting started

Install via UPM package with git reference or asset package(UniTask.*.*.*.unitypackage) available in UniTask/releases.

// extension awaiter/methods can be used by this namespace
using Cysharp.Threading.Tasks;

// You can return type as struct UniTask<T>(or UniTask), it is unity specialized lightweight alternative of Task<T>
// zero allocation and fast excution for zero overhead async/await integrate with Unity
async UniTask<string> DemoAsync()
{
    // You can await Unity's AsyncObject
    var asset = await Resources.LoadAsync<TextAsset>("foo");
    var txt = (await UnityWebRequest.Get("https://...").SendWebRequest()).downloadHandler.text;
    await SceneManager.LoadSceneAsync("scene2");

    // .WithCancellation enables Cancel, GetCancellationTokenOnDestroy synchornizes with lifetime of GameObject
    var asset2 = await Resources.LoadAsync<TextAsset>("bar").WithCancellation(this.GetCancellationTokenOnDestroy());

    // .ToUniTask accepts progress callback(and all options), Progress.Create is a lightweight alternative of IProgress<T>
    var asset3 = await Resources.LoadAsync<TextAsset>("baz").ToUniTask(Progress.Create<float>(x => Debug.Log(x)));

    // await frame-based operation like a coroutine
    await UniTask.DelayFrame(100); 

    // replacement of yield return new WaitForSeconds/WaitForSecondsRealtime
    await UniTask.Delay(TimeSpan.FromSeconds(10), ignoreTimeScale: false);
    
    // yield any playerloop timing(PreUpdate, Update, LateUpdate, etc...)
    await UniTask.Yield(PlayerLoopTiming.PreLateUpdate);

    // replacement of yield return null
    await UniTask.Yield();
    await UniTask.NextFrame();

    // replacement of WaitForEndOfFrame
#if UNITY_2023_1_OR_NEWER
    await UniTask.WaitForEndOfFrame();
#else
    // requires MonoBehaviour(CoroutineRunner))
    await UniTask.WaitForEndOfFrame(this); // this is MonoBehaviour
#endif

    // replacement of yield return new WaitForFixedUpdate(same as UniTask.Yield(PlayerLoopTiming.FixedUpdate))
    await UniTask.WaitForFixedUpdate();
    
    // replacement of yield return WaitUntil
    await UniTask.WaitUntil(() => isActive == false);

    // special helper of WaitUntil
    await UniTask.WaitUntilValueChanged(this, x => x.isActive);

    // You can await IEnumerator coroutines
    await FooCoroutineEnumerator();

    // You can await a standard task
    await Task.Run(() => 100);

    // Multithreading, run on ThreadPool under this code
    await UniTask.SwitchToThreadPool();

    /* work on ThreadPool */

    // return to MainThread(same as `ObserveOnMainThread` in UniRx)
    await UniTask.SwitchToMainThread();

    // get async webrequest
    async UniTask<string> GetTextAsync(UnityWebRequest req)
    {
        var op = await req.SendWebRequest();
        return op.downloadHandler.text;
    }

    var task1 = GetTextAsync(UnityWebRequest.Get("http://google.com"));
    var task2 = GetTextAsync(UnityWebRequest.Get("http://bing.com"));
    var task3 = GetTextAsync(UnityWebRequest.Get("http://yahoo.com"));

    // concurrent async-wait and get results easily by tuple syntax
    var (google, bing, yahoo) = await UniTask.WhenAll(task1, task2, task3);

    // shorthand of WhenAll, tuple can await directly
    var (google2, bing2, yahoo2) = await (task1, task2, task3);

    // return async-value.(or you can use `UniTask`(no result), `UniTaskVoid`(fire and forget)).
    return (asset as TextAsset)?.text ?? throw new InvalidOperationException("Asset not found");
}

Basics of UniTask and AsyncOperation

UniTask features rely on C# 7.0(task-like custom async method builder feature) so the required Unity version is after Unity 2018.3, the official lowest version supported is Unity 2018.4.13f1.

Why is UniTask(custom task-like object) required? Because Task is too heavy and not matched to Unity threading (single-thread). UniTask does not use threads and SynchronizationContext/ExecutionContext because Unity's asynchronous object is automaticaly dispatched by Unity's engine layer. It achieves faster and lower allocation, and is completely integrated with Unity.

You can await AsyncOperation, ResourceRequest, AssetBundleRequest, AssetBundleCreateRequest, UnityWebRequestAsyncOperation, AsyncGPUReadbackRequest, IEnumerator and others when using Cysharp.Threading.Tasks;.

UniTask provides three pattern of extension methods.

* await asyncOperation;
* .WithCancellation(CancellationToken);
* .ToUniTask(IProgress, PlayerLoopTiming, CancellationToken);

WithCancellation is a simple version of ToUniTask, both return UniTask. For details of cancellation, see: Cancellation and Exception handling section.

Note: await directly is returned from native timing of PlayerLoop but WithCancellation and ToUniTask are returned from specified PlayerLoopTiming. For details of timing, see: PlayerLoop section.

Note: AssetBundleRequest has asset and allAssets, default await returns asset. If you want to get allAssets, you can use AwaitForAllAssets() method.

The type of UniTask can use utilities like UniTask.WhenAll, UniTask.WhenAny. They are like Task.WhenAll/Task.WhenAny but the return type is more useful. They return value tuples so you can deconstruct each result and pass multiple types.

public async UniTaskVoid LoadManyAsync()
{
    // parallel load.
    var (a, b, c) = await UniTask.WhenAll(
        LoadAsSprite("foo"),
        LoadAsSprite("bar"),
        LoadAsSprite("baz"));
}

async UniTask<Sprite> LoadAsSprite(string path)
{
    var resource = await Resources.LoadAsync<Sprite>(path);
    return (resource as Sprite);
}

If you want to convert a callback to UniTask, you can use UniTaskCompletionSource<T> which is a lightweight edition of TaskCompletionSource<T>.

public UniTask<int> WrapByUniTaskCompletionSource()
{
    var utcs = new UniTaskCompletionSource<int>();

    // when complete, call utcs.TrySetResult();
    // when failed, call utcs.TrySetException();
    // when cancel, call utcs.TrySetCanceled();

    return utcs.Task; //return UniTask<int>
}

You can convert Task -> UniTask: AsUniTask, UniTask -> UniTask<AsyncUnit>: AsAsyncUnitUniTask, UniTask<T> -> UniTask: AsUniTask. UniTask<T> -> UniTask's conversion cost is free.

If you want to convert async to coroutine, you can use .ToCoroutine(), this is useful if you want to only allow using the coroutine system.

UniTask can not await twice. This is a similar constraint to the ValueTask/IValueTaskSource introduced in .NET Standard 2.1.

The following operations should never be performed on a ValueTask instance:

• Awaiting the instance multiple times.
• Calling AsTask multiple times.
• Using .Result or .GetAwaiter().GetResult() when the operation hasn't yet completed, or using them multiple times.
• Using more than one of these techniques to consume the instance.

If you do any of the above, the results are undefined.

var task = UniTask.DelayFrame(10);
await task;
await task; // NG, throws Exception

Store to the class field, you can use UniTask.Lazy that supports calling multiple times. .Preserve() allows for multiple calls (internally cached results). This is useful when there are multiple calls in a function scope.

Also UniTaskCompletionSource can await multiple times and await from many callers.

Cancellation and Exception handling

Some UniTask factory methods have a CancellationToken cancellationToken = default parameter. Also some async operations for Unity have WithCancellation(CancellationToken) and ToUniTask(..., CancellationToken cancellation = default) extension methods.

You can pass CancellationToken to parameter by standard CancellationTokenSource.

var cts = new CancellationTokenSource();

cancelButton.onClick.AddListener(() =>
{
    cts.Cancel();
});

await UnityWebRequest.Get("http://google.co.jp").SendWebRequest().WithCancellation(cts.Token);

await UniTask.DelayFrame(1000, cancellationToken: cts.Token);

CancellationToken can be created by CancellationTokenSource or MonoBehaviour's extension method GetCancellationTokenOnDestroy.

// this CancellationToken lifecycle is same as GameObject.
await UniTask.DelayFrame(1000, cancellationToken: this.GetCancellationTokenOnDestroy());

For propagate Cancellation, all async method recommend to accept CancellationToken cancellationToken at last argument, and pass CancellationToken from root to end.

await FooAsync(this.GetCancellationTokenOnDestroy());

// ---

async UniTask FooAsync(CancellationToken cancellationToken)
{
    await BarAsync(cancellationToken);
}

async UniTask BarAsync(CancellationToken cancellationToken)
{
    await UniTask.Delay(TimeSpan.FromSeconds(3), cancellationToken);
}

CancellationToken means lifecycle of async. You can hold your own lifecycle insteadof default CancellationTokenOnDestroy.

public class MyBehaviour : MonoBehaviour
{
    CancellationTokenSource disableCancellation = new CancellationTokenSource();
    CancellationTokenSource destroyCancellation = new CancellationTokenSource();

    private void OnEnable()
    {
        if (disableCancellation != null)
        {
            disableCancellation.Dispose();
        }
        disableCancellation = new CancellationTokenSource();
    }

    private void OnDisable()
    {
        disableCancellation.Cancel();
    }

    private void OnDestroy()
    {
        destroyCancellation.Cancel();
        destroyCancellation.Dispose();
    }
}

When cancellation is detected, all methods throw OperationCanceledException and propagate upstream. When exception(not limited to OperationCanceledException) is not handled in async method, it is propagated finally to UniTaskScheduler.UnobservedTaskException. The default behaviour of received unhandled exception is to write log as exception. Log level can be changed using UniTaskScheduler.UnobservedExceptionWriteLogType. If you want to use custom behaviour, set an action to UniTaskScheduler.UnobservedTaskException.

And also OperationCanceledException is a special exception, this is silently ignored at UnobservedTaskException.

If you want to cancel behaviour in an async UniTask method, throw OperationCanceledException manually.

public async UniTask<int> FooAsync()
{
    await UniTask.Yield();
    throw new OperationCanceledException();
}

If you handle an exception but want to ignore(propagate to global cancellation handling), use an exception filter.

public async UniTask<int> BarAsync()
{
    try
    {
        var x = await FooAsync();
        return x * 2;
    }
    catch (Exception ex) when (!(ex is OperationCanceledException)) // when (ex is not OperationCanceledException) at C# 9.0
    {
        return -1;
    }
}

throws/catch OperationCanceledException is slightly heavy, so if performance is a concern, use UniTask.SuppressCancellationThrow to avoid OperationCanceledException throw. It returns (bool IsCanceled, T Result) instead of throwing.

var (isCanceled, _) = await UniTask.DelayFrame(10, cancellationToken: cts.Token).SuppressCancellationThrow();
if (isCanceled)
{
    // ...
}

Note: Only suppress throws if you call directly into the most source method. Otherwise, the return value will be converted, but the entire pipeline will not suppress throws.

Some features that use Unity's player loop, such as UniTask.Yield and UniTask.Delay etc, determines CancellationToken state on the player loop. This means it does not cancel immediately upon CancellationToken fired.

If you want to change this behaviour, the cancellation to be immediate, set the cancelImmediately flag as an argument.

await UniTask.Yield(cancellationToken, cancelImmediately: true);

Note: Setting cancelImmediately to true and detecting an immediate cancellation is more costly than the default behavior. This is because it uses CancellationToken.Register; it is heavier than checking CancellationToken on the player loop.

Timeout handling

Timeout is a variation of cancellation. You can set timeout by CancellationTokenSouce.CancelAfterSlim(TimeSpan) and pass CancellationToken to async methods.

var cts = new CancellationTokenSource();
cts.CancelAfterSlim(TimeSpan.FromSeconds(5)); // 5sec timeout.

try
{
    await UnityWebRequest.Get("http://foo").SendWebRequest().WithCancellation(cts.Token);
}
catch (OperationCanceledException ex)
{
    if (ex.CancellationToken == cts.Token)
    {
        UnityEngine.Debug.Log("Timeout");
    }
}

CancellationTokenSouce.CancelAfter is a standard api. However in Unity you should not use it because it depends threading timer. CancelAfterSlim is UniTask's extension methods, it uses PlayerLoop instead.

If you want to use timeout with other source of cancellation, use CancellationTokenSource.CreateLinkedTokenSource.

var cancelToken = new CancellationTokenSource();
cancelButton.onClick.AddListener(() =>
{
    cancelToken.Cancel(); // cancel from button click.
});

var timeoutToken = new CancellationTokenSource();
timeoutToken.CancelAfterSlim(TimeSpan.FromSeconds(5)); // 5sec timeout.

try
{
    // combine token
    var linkedTokenSource = CancellationTokenSource.CreateLinkedTokenSource(cancelToken.Token, timeoutToken.Token);

    await UnityWebRequest.Get("http://foo").SendWebRequest().WithCancellation(linkedTokenSource.Token);
}
catch (OperationCanceledException ex)
{
    if (timeoutToken.IsCancellationRequested)
    {
        UnityEngine.Debug.Log("Timeout.");
    }
    else if (cancelToken.IsCancellationRequested)
    {
        UnityEngine.Debug.Log("Cancel clicked.");
    }
}

Optimize for reduce allocation of CancellationTokenSource for timeout per call async method, you can use UniTask's TimeoutController.

TimeoutController timeoutController = new TimeoutController(); // setup to field for reuse.

async UniTask FooAsync()
{
    try
    {
        // you can pass timeoutController.Timeout(TimeSpan) to cancellationToken.
        await UnityWebRequest.Get("http://foo").SendWebRequest()
            .WithCancellation(timeoutController.Timeout(TimeSpan.FromSeconds(5)));
        timeoutController.Reset(); // call Reset(Stop timeout timer and ready for reuse) when succeed.
    }
    catch