UniTask/README.md

933 lines
37 KiB
Markdown
Raw Normal View History

2020-05-19 02:33:44 +08:00
UniTask
===
[![GitHub Actions](https://github.com/Cysharp/UniTask/workflows/Build-Debug/badge.svg)](https://github.com/Cysharp/UniTask/actions) [![Releases](https://img.shields.io/github/release/Cysharp/UniTask.svg)](https://github.com/Cysharp/UniTask/releases)
2020-06-12 15:59:14 +08:00
Provides an efficient allocation free async/await integration to Unity.
2020-06-04 13:52:42 +08:00
* Struct based `UniTask<T>` and custom AsyncMethodBuilder to achive zero allocation
* All Unity AsyncOperations and Coroutine to awaitable
2020-06-04 14:31:42 +08:00
* PlayerLoop based task(`UniTask.Yield`, `UniTask.Delay`, `UniTask.DelayFrame`, etc..) that enable to replace all coroutine operation
2020-06-04 13:52:42 +08:00
* MonoBehaviour Message Events and uGUI Events as awaitable/async-enumerable
* Completely run on Unity's PlayerLoop so don't use thread and run on WebGL, wasm, etc.
* Asynchronous LINQ, with Channel and AsyncReactiveProperty
* TaskTracker window to prevent memory leak
* Highly compatible behaviour with Task/ValueTask/IValueTaskSource
2020-05-19 02:33:44 +08:00
2020-06-12 16:18:31 +08:00
Techinical details, see blog post: [UniTask v2 — Zero Allocation async/await for Unity, with Asynchronous LINQ
2020-06-12 16:18:22 +08:00
](https://medium.com/@neuecc/unitask-v2-zero-allocation-async-await-for-unity-with-asynchronous-linq-1aa9c96aa7dd)
2020-05-17 15:50:05 +08:00
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents
2020-05-19 02:34:05 +08:00
- [Getting started](#getting-started)
2020-06-04 13:53:07 +08:00
- [Basics of UniTask and AsyncOperation](#basics-of-unitask-and-asyncoperation)
2020-05-19 02:34:05 +08:00
- [Cancellation and Exception handling](#cancellation-and-exception-handling)
- [Progress](#progress)
2020-06-04 13:53:07 +08:00
- [PlayerLoop](#playerloop)
- [async void vs async UniTaskVoid](#async-void-vs-async-unitaskvoid)
2020-05-19 02:34:05 +08:00
- [UniTaskTracker](#unitasktracker)
2020-06-04 13:53:07 +08:00
- [External Assets](#external-assets)
- [AsyncEnumerable and Async LINQ](#asyncenumerable-and-async-linq)
- [Awaitable Events](#awaitable-events)
- [Channel](#channel)
2020-05-19 02:34:05 +08:00
- [For Unit Testing](#for-unit-testing)
2020-06-11 16:44:42 +08:00
- [Compare with Standard Task API](#compare-with-standard-task-api)
2020-06-04 16:54:24 +08:00
- [Pooling Configuration](#pooling-configuration)
2020-07-30 07:18:59 +08:00
- [UniTaskSynchronizationContext](#unitasksynchronizationcontext)
2020-06-04 13:53:07 +08:00
- [API References](#api-references)
2020-05-19 02:34:05 +08:00
- [UPM Package](#upm-package)
2020-06-04 13:53:07 +08:00
- [Install via git URL](#install-via-git-url)
- [Install via OpenUPM](#install-via-openupm)
- [.NET Core](#net-core)
2020-05-19 02:34:05 +08:00
- [License](#license)
2020-05-17 15:50:05 +08:00
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2019-06-06 10:53:07 +08:00
Getting started
---
2020-06-04 13:52:42 +08:00
Install via [UPM package](#upm-package) or asset package(`UniTask.*.*.*.unitypackage`) available in [UniTask/releases](https://github.com/Cysharp/UniTask/releases) page.
2019-06-06 10:53:07 +08:00
```csharp
// extension awaiter/methods can be used by this namespace
2020-06-04 13:52:42 +08:00
using Cysharp.Threading.Tasks;
2019-06-06 10:53:07 +08:00
// You can return type as struct UniTask<T>(or UniTask), it is unity specialized lightweight alternative of Task<T>
2020-06-04 13:52:42 +08:00
// zero allocation and fast excution for zero overhead async/await integrate with Unity
2019-06-06 10:53:07 +08:00
async UniTask<string> DemoAsync()
{
// You can await Unity's AsyncObject
var asset = await Resources.LoadAsync<TextAsset>("foo");
2020-06-08 00:45:57 +08:00
var txt = (await UnityWebRequest.Get("https://...").SendWebRequest()).downloadHandler.text;
await SceneManager.LoadSceneAsync("scene2");
2020-06-04 13:52:42 +08:00
// .WithCancellation enables Cancel, GetCancellationTokenOnDestroy synchornizes with lifetime of GameObject
2020-06-08 00:45:57 +08:00
var asset2 = await Resources.LoadAsync<TextAsset>("bar").WithCancellation(this.GetCancellationTokenOnDestroy());
2020-06-04 13:52:42 +08:00
// .ToUniTask accepts progress callback(and all options), Progress.Create is a lightweight alternative of IProgress<T>
2020-06-08 00:45:57 +08:00
var asset3 = await Resources.LoadAsync<TextAsset>("baz").ToUniTask(Progress.Create<float>(x => Debug.Log(x)));
2019-06-06 10:53:07 +08:00
// await frame-based operation like coroutine
await UniTask.DelayFrame(100);
2020-06-08 00:45:57 +08:00
// replacement of yield return new WaitForSeconds/WaitForSecondsRealtime
2019-06-06 10:53:07 +08:00
await UniTask.Delay(TimeSpan.FromSeconds(10), ignoreTimeScale: false);
2020-06-08 00:45:57 +08:00
// yield any playerloop timing(PreUpdate, Update, LateUpdate, etc...)
await UniTask.Yield(PlayerLoopTiming.PreLateUpdate);
// replacement of yield return null
2020-06-08 01:22:10 +08:00
await UniTask.Yield();
2020-06-08 00:45:57 +08:00
await UniTask.NextFrame();
// replacement of WaitForEndOfFrame(same as UniTask.Yield(PlayerLoopTiming.LastPostLateUpdate))
await UniTask.WaitForEndOfFrame();
2020-06-08 01:22:10 +08:00
// replacement of yield return new WaitForFixedUpdate(same as UniTask.Yield(PlayerLoopTiming.FixedUpdate))
await UniTask.WaitForFixedUpdate();
2019-06-06 10:53:07 +08:00
// replacement of yield return WaitUntil
await UniTask.WaitUntil(() => isActive == false);
2020-06-04 13:52:42 +08:00
// special helper of WaitUntil
await UniTask.WaitUntilValueChanged(this, x => x.isActive);
2019-06-06 10:53:07 +08:00
// You can await IEnumerator coroutine
await FooCoroutineEnumerator();
// You can await standard task
await Task.Run(() => 100);
2020-06-08 01:22:10 +08:00
// Multithreading, run on ThreadPool under this code
2019-06-06 10:53:07 +08:00
await UniTask.SwitchToThreadPool();
2020-06-08 01:22:10 +08:00
/* work on ThreadPool */
// return to MainThread(same as `ObserveOnMainThread` in UniRx)
await UniTask.SwitchToMainThread();
2019-06-06 10:53:07 +08:00
// 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 result easily by tuple syntax
var (google, bing, yahoo) = await UniTask.WhenAll(task1, task2, task3);
2020-06-04 13:52:42 +08:00
// shorthand of WhenAll, tuple can await directly
var (google2, bing2, yahoo2) = await (task1, task2, task3);
2019-06-06 10:53:07 +08:00
// You can handle timeout easily
await GetTextAsync(UnityWebRequest.Get("http://unity.com")).Timeout(TimeSpan.FromMilliseconds(300));
// 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");
}
```
2020-06-04 13:52:42 +08:00
Basics of UniTask and AsyncOperation
2019-06-06 10:53:07 +08:00
---
2020-06-04 13:52:42 +08:00
UniTask feature rely on C# 7.0([task-like custom async method builder feature](https://github.com/dotnet/roslyn/blob/master/docs/features/task-types.md)) so required Unity version is after `Unity 2018.3`, officialy lower support version is `Unity 2018.4.13f1`.
2020-03-16 22:36:46 +08:00
2020-06-04 13:52:42 +08:00
Why UniTask(custom task-like object) is required? Because Task is too heavy, not matched to Unity threading(single-thread). UniTask does not use thread and SynchronizationContext/ExecutionContext because almost Unity's asynchronous object is automaticaly dispatched by Unity's engine layer. It acquires more fast and more less allocation, completely integrated with Unity.
2019-06-06 10:53:07 +08:00
2020-06-29 00:12:48 +08:00
You can await `AsyncOperation`, `ResourceRequest`, `AssetBundleRequest`, `AssetBundleCreateRequest`, `UnityWebRequestAsyncOperation`, `AsyncGPUReadbackRequest`, `IEnumerator` and others when `using Cysharp.Threading.Tasks;`.
2019-06-06 10:53:07 +08:00
2020-06-04 13:52:42 +08:00
UniTask provides three pattern of extension methods.
2019-06-06 10:53:07 +08:00
```csharp
2020-06-04 13:52:42 +08:00
* await asyncOperation;
* .WithCancellation(CancellationToken);
* .ToUniTask(IProgress, PlayerLoopTiming, CancellationToken);
2019-06-06 10:53:07 +08:00
```
2020-06-04 13:52:42 +08:00
`WithCancellation` is a simple version of `ToUniTask`, both returns `UniTask`. Details of cancellation, see: [Cancellation and Exception handling](#cancellation-and-exception-handling) section.
2019-06-06 10:53:07 +08:00
2020-06-08 00:45:57 +08:00
> Note: WithCancellation is returned from native timing of PlayerLoop but ToUniTask is returned from specified PlayerLoopTiming. Details of timing, see: [PlayerLoop](#playerloop) section.
2020-06-04 13:52:42 +08:00
The type of `UniTask` can use utility like `UniTask.WhenAll`, `UniTask.WhenAny`. It is like Task.WhenAll/WhenAny but return type is more useful, returns value tuple so can deconsrtuct each result and pass multiple type.
2019-06-06 10:53:07 +08:00
```csharp
public class SceneAssets
{
public SceneAssets()
{
2020-06-04 13:52:42 +08:00
// parallel load.
var (a, b, c) = await UniTask.WhenAll(
LoadAsSprite("foo"),
LoadAsSprite("bar"),
LoadAsSprite("baz"));
2019-06-06 10:53:07 +08:00
}
async UniTask<Sprite> LoadAsSprite(string path)
{
var resource = await Resources.LoadAsync<Sprite>(path);
return (resource as Sprite);
}
}
```
If you want to convert callback to UniTask, you can use `UniTaskCompletionSource<T>` that is the lightweight edition of `TaskCompletionSource<T>`.
```csharp
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>
}
```
2020-06-04 13:52:42 +08:00
You can convert Task -> UniTask: `AsUniTask`, `UniTask` -> `UniTask<AsyncUnit>`: `AsAsyncUnitUniTask`, `UniTask<T>` -> `UniTask`: `AsUniTask`. `UniTask<T>` -> `UniTask`'s conversion cost is free.
2019-06-06 10:53:07 +08:00
2020-06-04 13:52:42 +08:00
If you want to convert async to coroutine, you can use `.ToCoroutine()`, this is useful to use only allow coroutine system.
UniTask can not await twice. This is a similar constraint to the [ValueTask/IValueTaskSource](https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask-1?view=netcore-3.1) introduced in .NET Standard 2.1.
> The following operations should never be performed on a ValueTask<TResult> 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.
```csharp
var task = UniTask.DelayFrame(10);
await task;
await task; // NG, throws Exception
```
2020-06-21 22:11:47 +08:00
Store to the class field, you can use `UniTask.Lazy` that gurantee call multipletimes. `.Preserve()` allows for multiple calls (internally cached results). This is useful when multiple calls in a function scope.
2019-06-06 10:53:07 +08:00
2020-03-16 22:36:46 +08:00
Cancellation and Exception handling
2019-06-06 10:53:07 +08:00
---
2020-06-04 13:52:42 +08:00
Some UniTask factory methods have `CancellationToken cancellationToken = default` parameter. Andalso some async operation for unity have `WithCancellation(CancellationToken)` and `ToUniTask(..., CancellationToken cancellation = default)` extension methods.
2020-03-16 22:36:46 +08:00
You can pass `CancellationToken` to parameter by standard [`CancellationTokenSource`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.cancellationtokensource).
```csharp
var cts = new CancellationTokenSource();
cancelButton.onClick.AddListener(() =>
{
cts.Cancel();
});
2020-06-04 13:52:42 +08:00
await UnityWebRequest.Get("http://google.co.jp").SendWebRequest().WithCancellation(cts.Token);
2020-03-16 22:36:46 +08:00
await UniTask.DelayFrame(1000, cancellationToken: cts.Token);
```
CancellationToken can create by `CancellationTokenSource` or MonoBehaviour's extension method `GetCancellationTokenOnDestroy`.
```csharp
// this CancellationToken lifecycle is same as GameObject.
await UniTask.DelayFrame(1000, cancellationToken: this.GetCancellationTokenOnDestroy());
```
2020-03-16 22:36:46 +08:00
When detect cancellation, all methods throws `OperationCanceledException` and propagate to upstream. `OperationCanceledException` is special exception, if not handled this exception, finally it is propagated to `UniTaskScheduler.UnobservedTaskException`.
2020-06-04 13:52:42 +08:00
Default behaviour of received unhandled exception is write log as exception. Log level can change by `UniTaskScheduler.UnobservedExceptionWriteLogType`. If you want to change custom beavhiour, set action to `UniTaskScheduler.UnobservedTaskException.`
2019-06-06 10:53:07 +08:00
2020-03-16 22:36:46 +08:00
If you want to cancel behaviour in async UniTask method, throws `OperationCanceledException` manually.
```csharp
public async UniTask<int> FooAsync()
{
await UniTask.Yield();
throw new OperationCanceledException();
}
```
If you handle exception but want to ignore(propagete to global cancellation handling), use exception filter.
```csharp
public async UniTask<int> BarAsync()
{
try
{
var x = await FooAsync();
return x * 2;
}
catch (Exception ex) when (!(ex is OperationCanceledException))
{
return -1;
}
}
```
throws/catch `OperationCanceledException` is slightly heavy, if you want to care performance, use `UniTask.SuppressCancellationThrow` to avoid OperationCanceledException throw. It returns `(bool IsCanceled, T Result)` instead of throw.
```csharp
var (isCanceled, _) = await UniTask.DelayFrame(10, cancellationToken: cts.Token).SuppressCancellationThrow();
if (isCanceled)
{
// ...
}
```
2020-06-04 13:52:42 +08:00
Note: Only suppress throws if you call it directly into the most source method. Otherwise, the return value will be converted, but the entire pipeline will not be suppressed throws.
2020-03-16 22:36:46 +08:00
Progress
2019-06-06 10:53:07 +08:00
---
2020-06-04 13:52:42 +08:00
Some async operation for unity have `ToUniTask(IProgress<float> progress = null, ...)` extension methods.
2020-03-16 22:36:46 +08:00
```csharp
var progress = Progress.Create<float>(x => Debug.Log(x));
var request = await UnityWebRequest.Get("http://google.co.jp")
.SendWebRequest()
2020-06-04 13:52:42 +08:00
.ToUniTask(progress: progress);
2020-03-16 22:36:46 +08:00
```
2020-06-04 13:52:42 +08:00
You should not use standard `new System.Progress<T>`, because it causes allocation every times. Use `Cysharp.Threading.Tasks.Progress` instead. This progress factory has two methods, `Create` and `CreateOnlyValueChanged`. `CreateOnlyValueChanged` calls only when progress value changed.
2020-03-16 22:36:46 +08:00
2020-06-04 13:52:42 +08:00
Implements IProgress interface to caller is more better, there is no allocation of lambda.
2020-03-16 22:36:46 +08:00
```csharp
public class Foo : MonoBehaviour, IProgress<float>
{
public void Report(float value)
{
UnityEngine.Debug.Log(value);
}
public async UniTaskVoid WebRequest()
{
var request = await UnityWebRequest.Get("http://google.co.jp")
.SendWebRequest()
2020-06-04 13:52:42 +08:00
.ToUniTask(progress: this); // pass this
2020-03-16 22:36:46 +08:00
}
}
```
2019-06-06 10:53:07 +08:00
2020-06-04 13:52:42 +08:00
PlayerLoop
---
UniTask is run on custom [PlayerLoop](https://docs.unity3d.com/ScriptReference/LowLevel.PlayerLoop.html). UniTask's playerloop based method(such as `Delay`, `DelayFrame`, `asyncOperation.ToUniTask`, etc...) accepts this `PlayerLoopTiming`.
```csharp
public enum PlayerLoopTiming
{
Initialization = 0,
LastInitialization = 1,
EarlyUpdate = 2,
LastEarlyUpdate = 3,
FixedUpdate = 4,
LastFixedUpdate = 5,
PreUpdate = 6,
LastPreUpdate = 7,
Update = 8,
LastUpdate = 9,
PreLateUpdate = 10,
LastPreLateUpdate = 11,
PostLateUpdate = 12,
LastPostLateUpdate = 13
}
```
It indicates when to run, you can check [PlayerLoopList.md](https://gist.github.com/neuecc/bc3a1cfd4d74501ad057e49efcd7bdae) to Unity's default playerloop and injected UniTask's custom loop.
2020-06-08 01:22:10 +08:00
`PlayerLoopTiming.Update` is similar as `yield return null` in coroutine, but it is called before Update(Update and uGUI events(button.onClick, etc...) are called on `ScriptRunBehaviourUpdate`, yield return null is called on `ScriptRunDelayedDynamicFrameRate`). `PlayerLoopTiming.FixedUpdate` is similar as `WaitForFixedUpdate`, `PlayerLoopTiming.LastPostLateUpdate` is similar as `WaitForEndOfFrame` in coroutine.
2020-06-04 13:52:42 +08:00
2020-06-08 00:45:57 +08:00
`yield return null` and `UniTask.Yield` is similar but different. `yield return null` always return next frame but `UniTask.Yield` return next called, that is, call `UniTask.Yield(PlayerLoopTiming.Update)` on `PreUpdate`, it returns same frame. `UniTask.NextFrame()` gurantees return next frame, this would be expected to behave exactly the same as `yield return null`.
2020-06-08 01:22:10 +08:00
> UniTask.Yield(without CancellationToken) is a special type, returns `YieldAwaitable` and run on YieldRunner. It is most lightweight and faster.
2020-06-11 22:50:13 +08:00
AsyncOperation is returned from native timing. For example, await `SceneManager.LoadSceneAsync` is returned from `EarlyUpdate.UpdatePreloading` and after called, loaded scene's `Start` called from `EarlyUpdate.ScriptRunDelayedStartupFrame`. Also `await UnityWebRequest` is returned from `EarlyUpdate.ExecuteMainThreadJobs`.
2020-06-08 00:45:57 +08:00
In UniTask, await directly and `WithCancellation` use native timing, `ToUniTask` use specified timing. This is usually not a particular problem, but with `LoadSceneAsync`, causes different order of Start and continuation after await. so recommend not to use `LoadSceneAsync.ToUniTask`.
2020-06-04 16:53:57 +08:00
In stacktrace, you can check where is running in playerloop.
![image](https://user-images.githubusercontent.com/46207/83735571-83caea80-a68b-11ea-8d22-5e22864f0d24.png)
2020-06-04 13:52:42 +08:00
In default, UniTask's PlayerLoop is initialized at `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]`.
The order in which methods are called in BeforeSceneLoad is indeterminate, so if you want to use UniTask in other BeforeSceneLoad methods, you should try to initialize it before this.
```csharp
// AfterAssembliesLoaded is called before BeforeSceneLoad
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]
public static void InitUniTaskLoop()
{
var loop = PlayerLoop.GetCurrentPlayerLoop();
Cysharp.Threading.Tasks.PlayerLoopHelper.Initialize(ref loop);
}
```
If you import Unity's `Entities` package, that reset custom player loop to default at `BeforeSceneLoad` and inject ECS's loop. When Unity call ECS's inject method after UniTask's initialize method, UniTask will no longer work.
To solve this issue, you can re-initialize UniTask PlayerLoop after ECS initialized.
```csharp
// Get ECS Loop.
var playerLoop = ScriptBehaviourUpdateOrder.CurrentPlayerLoop;
// Setup UniTask's PlayerLoop.
PlayerLoopHelper.Initialize(ref playerLoop);
```
You can diagnostic UniTask's player loop is ready by `PlayerLoopHelper.IsInjectedUniTaskPlayerLoop()`. And also `PlayerLoopHelper.DumpCurrentPlayerLoop` shows current all playerloop to console.
```csharp
void Start()
{
UnityEngine.Debug.Log("UniTaskPlayerLoop ready? " + PlayerLoopHelper.IsInjectedUniTaskPlayerLoop());
PlayerLoopHelper.DumpCurrentPlayerLoop();
}
```
2020-06-04 13:52:42 +08:00
async void vs async UniTaskVoid
---
2020-06-26 16:57:27 +08:00
`async void` is a standard C# task system so does not run on UniTask systems. It is better not to use. `async UniTaskVoid` is a lightweight version of `async UniTask` because it does not have awaitable completion and report error immediately to `UniTaskScheduler.UnobservedTaskException`. If you don't require to await it(fire and forget), use `UniTaskVoid` is better. Unfortunately to dismiss warning, require to using with `Forget()`.
2020-06-04 13:52:42 +08:00
```csharp
public async UniTaskVoid FireAndForgetMethod()
{
// do anything...
await UniTask.Yield();
}
public void Caller()
{
FireAndForgetMethod().Forget();
}
```
Also UniTask have `Forget` method, it is similar with UniTaskVoid and same effects with it. However still UniTaskVoid is more efficient if completely do not use await。
```csharp
public async UniTask DoAsync()
{
// do anything...
await UniTask.Yield();
}
public void Caller()
{
DoAsync().Forget();
}
```
Using async lambda in register event, it is used `async void`. To avoid it, you can use `UniTask.Action` or `UniTask.UnityAction` that creates delegate via `async UniTaskVoid` lambda.
```csharp
Action actEvent;
UnityAction unityEvent; // especially used in uGUI
// Bad: async void
actEvent += async () => { };
unityEvent += async () => { };
// Ok: create Action delegate by lambda
actEvent += UniTask.Action(async () => { await UniTask.Yield(); });
unityEvent += UniTask.UnityAction(async () => { await UniTask.Yield(); });
```
2020-06-26 16:53:07 +08:00
`UniTaskVoid` can also use in MonoBehaviour's `Start` method.
```csharp
class Sample : MonoBehaviour
{
async UniTaskVoid Start()
{
// async init code.
}
}
```
2019-06-06 10:53:07 +08:00
UniTaskTracker
---
2020-04-16 20:08:56 +08:00
useful for check(leak) UniTasks. You can open tracker window in `Window -> UniTask Tracker`.
2019-06-06 10:53:07 +08:00
2020-06-04 13:52:42 +08:00
![image](https://user-images.githubusercontent.com/46207/83527073-4434bf00-a522-11ea-86e9-3b3975b26266.png)
2019-06-06 10:53:07 +08:00
2020-03-16 22:36:46 +08:00
* Enable AutoReload(Toggle) - Reload automatically.
* Reload - Reload view.
* GC.Collect - Invoke GC.Collect.
* Enable Tracking(Toggle) - Start to track async/await UniTask. Performance impact: low.
* Enable StackTrace(Toggle) - Capture StackTrace when task is started. Performance impact: high.
For debug use, enable tracking and capture stacktrace is useful but it it decline performance. Recommended usage is enable both to find task leak, and when done, finally disable both.
2020-06-04 13:52:42 +08:00
External Assets
2020-03-16 22:36:46 +08:00
---
In default, UniTask supports TextMeshPro(`BindTo(TMP_Text)` and `TMP_InputField` event extensions like standard uGUI `InputField`), DOTween(`Tween` as awaitable) and Addressables(`AsyncOperationHandle` and `AsyncOpereationHandle<T>` as awaitable).
2020-06-04 13:52:42 +08:00
There are defined in separated asmdef like `UniTask.TextMeshPro`, `UniTask.DOTween`, `UniTask.Addressables`.
TextMeshPro and Addressables support are automatically enabled when import there package from package manager. However DOTween support, require to `com.demigiant.dotween` import from [OpenUPM](https://openupm.com/packages/com.demigiant.dotween/) or define `UNITASK_DOTWEEN_SUPPORT` to enable it.
2020-03-16 22:36:46 +08:00
```csharp
2020-06-04 13:52:42 +08:00
// sequential
await transform.DOMoveX(2, 10);
await transform.DOMoveZ(5, 20);
// parallel with cancellation
var ct = this.GetCancellationTokenOnDestroy();
await UniTask.WhenAll(
transform.DOMoveX(10, 3).WithCancellation(ct),
transform.DOScale(10, 3).WithCancellation(ct));
```
AsyncEnumerable and Async LINQ
---
Unity 2020.2.0a12 supports C# 8.0 so you can use `await foreach`. This is the new Update notation in async era.
2020-03-16 22:36:46 +08:00
2020-06-04 13:52:42 +08:00
```csharp
// Unity 2020.2.0a12, C# 8.0
await foreach (var _ in UniTaskAsyncEnumerable.EveryUpdate(token))
2020-03-16 22:36:46 +08:00
{
2020-06-04 13:52:42 +08:00
Debug.Log("Update() " + Time.frameCount);
2020-03-16 22:36:46 +08:00
}
```
2020-06-04 13:52:42 +08:00
In a C# 7.3 environment, you can use the `ForEachAsync` method to work in almost the same way.
2019-06-06 10:53:07 +08:00
```csharp
2020-06-04 13:52:42 +08:00
// C# 7.3(Unity 2018.3~)
await UniTaskAsyncEnumerable.EveryUpdate(token).ForEachAsync(_ =>
{
Debug.Log("Update() " + Time.frameCount);
});
```
2020-03-16 22:36:46 +08:00
2020-06-04 13:52:42 +08:00
UniTaskAsyncEnumerable implements asynchronous LINQ, similar to LINQ in `IEnumerable<T>` or Rx in `IObservable<T>`. All standard LINQ query operators can be applied to asynchronous streams. For example, the following code shows how to apply a Where filter to a button-click asynchronous stream that runs once every two clicks.
```csharp
await okButton.OnClickAsAsyncEnumerable().Where((x, i) => i % 2 == 0).ForEachAsync(_ =>
{
});
```
2020-06-15 21:46:01 +08:00
Fire and Forget style(for example, event handling), also you can use `Subscribe`.
```csharp
okButton.OnClickAsAsyncEnumerable().Where((x, i) => i % 2 == 0).Subscribe(_ =>
{
});
```
2020-06-04 13:52:42 +08:00
Async LINQ is enabled when `using Cysharp.Threading.Tasks.Linq;`, and `UniTaskAsyncEnumerable` is defined in `UniTask.Linq` asmdef.
It's closer to UniRx (Reactive Extensions), but UniTaskAsyncEnumerable is a pull-based asynchronous stream, whereas Rx was a push-based asynchronous stream. Note that although similar, the characteristics are different and the details behave differently along with them.
2020-06-29 00:18:16 +08:00
`UniTaskAsyncEnumerable` is the entry point like `Enumerbale`. In addition to the standard query operators, there are other generators for Unity such as `EveryUpdate`, `Timer`, `TimerFrame`, `Interval`, `IntervalFrame`, and `EveryValueChanged`. And also added additional UniTask original query operators like `Append`, `Prepend`, `DistinctUntilChanged`, `ToHashSet`, `Buffer`, `CombineLatest`, `Do`, `Never`, `ForEachAsync`, `Pairwise`, `Publish`, `Queue`, `Return`, `SkipUntil`, `TakeUntil`, `SkipUntilCanceled`, `TakeUntilCanceled`, `TakeLast`, `Subscribe`.
2020-06-04 13:52:42 +08:00
The method with Func as an argument has three additional overloads, `***Await`, `***AwaitWithCancellation`.
```csharp
Select(Func<T, TR> selector)
SelectAwait(Func<T, UniTask<TR>> selector)
SelectAwaitWithCancellation(Func<T, CancellationToken, UniTask<TR>> selector)
```
If you want to use the `async` method inside the func, use the `***Await` or `***AwaitWithCancellation`.
2020-07-04 05:36:14 +08:00
How to create async iterator, C# 8.0 supports async iterator(`async yield return`) but it only allows `IAsyncEnumerable<T>` and of course requires C# 8.0. UniTask supports `UniTaskAsyncEnumerable.Create` method to create custom async iterator.
```csharp
// IAsyncEnumerable, C# 8.0 version of async iterator. ( do not use this style, IAsyncEnumerable is not controled in UniTask).
2020-07-04 05:44:57 +08:00
public async IAsyncEnumerable<int> MyEveryUpdate([EnumeratorCancellation]CancellationToken cancelationToken = default)
2020-07-04 05:36:14 +08:00
{
var frameCount = 0;
await UniTask.Yield();
while (!token.IsCancellationRequested)
{
yield return frameCount++;
await UniTask.Yield();
}
}
// UniTaskAsyncEnumerable.Create and use `await writer.YieldAsync` instead of `yield return`.
public IUniTaskAsyncEnumerable<int> MyEveryUpdate()
{
// writer(IAsyncWriter<T>) has `YieldAsync(value)` method.
return UniTaskAsyncEnumerable.Create<int>(async (writer, token) =>
{
var frameCount = 0;
await UniTask.Yield();
while (!token.IsCancellationRequested)
{
await writer.YieldAsync(frameCount++); // instead of `yield return`
await UniTask.Yield();
}
});
}
```
2020-06-04 13:52:42 +08:00
Awaitable Events
---
All uGUI component implements `***AsAsyncEnumerable` to convert asynchronous streams of events.
```csharp
async UniTask TripleClick()
2019-06-06 10:53:07 +08:00
{
2020-06-04 13:52:42 +08:00
// In default, used button.GetCancellationTokenOnDestroy to manage lieftime of async
await button.OnClickAsync();
await button.OnClickAsync();
await button.OnClickAsync();
2019-06-06 10:53:07 +08:00
Debug.Log("Three times clicked");
}
// more efficient way
2020-06-04 13:52:42 +08:00
async UniTask TripleClick()
2019-06-06 10:53:07 +08:00
{
2020-06-04 13:52:42 +08:00
using (var handler = button.GetAsyncClickEventHandler())
2019-06-06 10:53:07 +08:00
{
await handler.OnClickAsync();
await handler.OnClickAsync();
await handler.OnClickAsync();
Debug.Log("Three times clicked");
}
}
2020-06-04 13:52:42 +08:00
// use async LINQ
async UniTask TripleClick(CancellationToken token)
{
await button.OnClickAsAsyncEnumerable().Take(3).Last();
Debug.Log("Three times clicked");
}
// use async LINQ2
async UniTask TripleClick(CancellationToken token)
{
await button.OnClickAsAsyncEnumerable().Take(3).ForEachAsync(_ =>
{
Debug.Log("Every clicked");
});
Debug.Log("Three times clicked, complete.");
}
2019-06-06 10:53:07 +08:00
```
2020-06-04 13:52:42 +08:00
All MonoBehaviour message events can convert async-streams by `AsyncTriggers` that can enable by `using Cysharp.Threading.Tasks.Triggers;`.
```csharp
using Cysharp.Threading.Tasks.Triggers;
async UniTaskVoid MonitorCollision()
{
await gameObject.OnCollisionEnterAsync();
Debug.Log("Collision Enter");
/* do anything */
await gameObject.OnCollisionExitAsync();
Debug.Log("Collision Exit");
}
```
Similar as uGUI event, AsyncTrigger can get by `GetAsync***Trigger` and trigger it self is UniTaskAsyncEnumerable.
```csharp
// use await multiple times, get AsyncTriggerHandler is more efficient.
using(var trigger = this.GetOnCollisionEnterAsyncHandler())
{
await OnCollisionEnterAsync();
await OnCollisionEnterAsync();
await OnCollisionEnterAsync();
}
// every moves.
await this.GetAsyncMoveTrigger().ForEachAsync(axisEventData =>
{
});
```
2020-06-11 22:50:13 +08:00
`AsyncReactiveProperty`, `AsyncReadOnlyReactiveProperty` is UniTask version of UniTask's ReactiveProperty. `BindTo` extension method of `IUniTaskAsyncEnumerable<T>` for binding asynchronous stream values to Unity components(Text/Selectable/TMP/Text).
2020-06-04 13:52:42 +08:00
2020-06-11 22:50:13 +08:00
```csharp
var rp = new AsyncReactiveProperty<int>(99);
// AsyncReactiveProperty itself is IUniTaskAsyncEnumerable, you can query by LINQ
rp.ForEachAsync(x =>
{
Debug.Log(x);
}, this.GetCancellationTokenOnDestroy()).Forget();
rp.Value = 10; // push 10 to all subscriber
rp.Value = 11; // push 11 to all subscriber
// WithoutCurrent ignore initial value
// BindTo bind stream value to unity components.
rp.WithoutCurrent().BindTo(this.textComponent);
await rp.WaitAsync(); // wait until next value set
// also exists ToReadOnlyReactiveProperty
var rp2 = new AsyncReactiveProperty<int>(99);
var rorp = rp.CombineLatest(rp2, (x, y) => (x, y)).ToReadOnlyReactiveProperty();
```
2020-06-04 13:52:42 +08:00
A pull-type asynchronous stream does not get the next values until the asynchronous processing in the sequence is complete. This could spill data from push-type events such as buttons.
```csharp
// can not get click event during 3 seconds complete.
2020-06-15 21:46:01 +08:00
await button.OnClickAsAsyncEnumerable().ForEachAwaitAsync(async x =>
2020-06-04 13:52:42 +08:00
{
await UniTask.Delay(TimeSpan.FromSeconds(3));
2020-06-15 21:46:01 +08:00
});
2020-06-04 13:52:42 +08:00
```
It is useful(prevent double-click) but not useful in sometimes.
Using `Queue()` method, which will also queue events during asynchronous processing.
```csharp
// queued message in asynchronous processing
2020-06-15 21:46:01 +08:00
await button.OnClickAsAsyncEnumerable().Queue().ForEachAwaitAsync(async x =>
2020-06-04 13:52:42 +08:00
{
await UniTask.Delay(TimeSpan.FromSeconds(3));
2020-06-15 21:46:01 +08:00
});
```
Or use `Subscribe`, fire and forget style.
```csharp
button.OnClickAsAsyncEnumerable().Subscribe(async x =>
{
await UniTask.Delay(TimeSpan.FromSeconds(3));
});
2020-06-04 13:52:42 +08:00
```
Channel
2020-03-16 22:36:46 +08:00
---
2020-06-04 13:52:42 +08:00
`Channel` is same as [System.Threading.Tasks.Channels](https://docs.microsoft.com/ja-jp/dotnet/api/system.threading.channels?view=netcore-3.1) that is similar as GoLang Channel.
Currently only supports multiple-producer, single-consumer unbounded channel. It can create by `Channel.CreateSingleConsumerUnbounded<T>()`.
For producer(`.Writer`), `TryWrite` to push value and `TryComplete` to complete channel. For consumer(`.Reader`), `TryRead`, `WaitToReadAsync`, `ReadAsync`, `Completion` and `ReadAllAsync` to read queued messages.
`ReadAllAsync` returns `IUniTaskAsyncEnumerable<T>` so query LINQ operators. Reader only allows single-consumer but use `.Publish()` query operator to enable multicast message. For example, make pub/sub utility.
```csharp
public class AsyncMessageBroker<T> : IDisposable
{
Channel<T> channel;
IConnectableUniTaskAsyncEnumerable<T> multicastSource;
IDisposable connection;
public AsyncMessageBroker()
{
channel = Channel.CreateSingleConsumerUnbounded<T>();
multicastSource = channel.Reader.ReadAllAsync().Publish();
connection = multicastSource.Connect(); // Publish returns IConnectableUniTaskAsyncEnumerable.
}
public void Publish(T value)
{
channel.Writer.TryWrite(value);
}
public IUniTaskAsyncEnumerable<T> Subscribe()
{
return multicastSource;
}
public void Dispose()
{
channel.Writer.TryComplete();
connection.Dispose();
}
}
```
2020-03-16 22:36:46 +08:00
For Unit Testing
---
Unity's `[UnityTest]` attribute can test coroutine(IEnumerator) but can not test async. `UniTask.ToCoroutine` bridges async/await to coroutine so you can test async method.
```csharp
[UnityTest]
public IEnumerator DelayIgnore() => UniTask.ToCoroutine(async () =>
{
var time = Time.realtimeSinceStartup;
Time.timeScale = 0.5f;
try
{
await UniTask.Delay(TimeSpan.FromSeconds(3), ignoreTimeScale: true);
var elapsed = Time.realtimeSinceStartup - time;
Assert.AreEqual(3, (int)Math.Round(TimeSpan.FromSeconds(elapsed).TotalSeconds, MidpointRounding.ToEven));
}
finally
{
Time.timeScale = 1.0f;
}
});
```
2020-06-04 13:52:42 +08:00
UniTask itself's unit test is written by Unity Test Runner and [Cysharp/RuntimeUnitTestToolkit](https://github.com/Cysharp/RuntimeUnitTestToolkit) to check on CI and IL2CPP working.
2020-06-11 16:44:22 +08:00
Compare with Standard Task API
---
UniTask has many standard Task-like APIs. This table shows what is the alternative apis.
Use standard type.
| .NET Type | UniTask Type |
2020-06-11 16:48:41 +08:00
| --- | --- |
2020-06-11 16:44:22 +08:00
| `IProgress<T>` | --- |
| `CancellationToken` | --- |
| `CancellationTokenSource` | --- |
Use UniTask type.
| .NET Type | UniTask Type |
2020-06-11 16:48:41 +08:00
| --- | --- |
2020-06-11 16:44:22 +08:00
| `Task`/`ValueTask` | `UniTask` |
| `Task<T>`/`ValueTask<T>` | `UniTask<T>` |
2020-06-11 19:21:51 +08:00
| `async void` | `async UniTaskVoid` |
2020-06-11 22:50:13 +08:00
| `+= async () => { }` | `UniTask.Void`, `UniTask.Action`, `UniTask.UnityAction` |
2020-06-11 16:44:22 +08:00
| --- | `UniTaskCompletionSource` |
| `TaskCompletionSource<T>` | `UniTaskCompletionSource<T>`/`AutoResetUniTaskCompletionSource<T>` |
| `ManualResetValueTaskSourceCore<T>` | `UniTaskCompletionSourceCore<T>` |
| `IValueTaskSource` | `IUniTaskSource` |
| `IValueTaskSource<T>` | `IUniTaskSource<T>` |
| `ValueTask.IsCompleted` | `UniTask.Status.IsCompleted()` |
| `ValueTask<T>.IsCompleted` | `UniTask<T>.Status.IsCompleted()` |
| `new Progress<T>` | `Progress.Create<T>` |
| `CancellationToken.Register(UnsafeRegister)` | `CancellationToken.RegisterWithoutCaptureExecutionContext` |
2020-06-11 22:50:13 +08:00
| `CancellationTokenSource.CancelAfter` | `CancellationTokenSource.CancelAfterSlim` |
2020-06-11 16:44:22 +08:00
| `Channel.CreateUnbounded<T>(false){ SingleReader = true }` | `Channel.CreateSingleConsumerUnbounded<T>` |
| `IAsyncEnumerable<T>` | `IUniTaskAsyncEnumerable<T>` |
| `IAsyncEnumerator<T>` | `IUniTaskAsyncEnumerator<T>` |
| `IAsyncDisposable` | `IUniTaskAsyncDisposable` |
| `Task.Delay` | `UniTask.Delay` |
| `Task.Yield` | `UniTask.Yield` |
| `Task.Run` | `UniTask.Run` |
| `Task.WhenAll` | `UniTask.WhenAll` |
| `Task.WhenAny` | `UniTask.WhenAny` |
| `Task.CompletedTask` | `UniTask.CompletedTask` |
| `Task.FromException` | `UniTask.FromException` |
| `Task.FromResult` | `UniTask.FromResult` |
| `Task.FromCanceled` | `UniTask.FromCanceled` |
| `Task.ContinueWith` | `UniTask.ContinueWith` |
| `TaskScheduler.UnobservedTaskException` | `UniTaskScheduler.UnobservedTaskException` |
2020-06-04 16:53:57 +08:00
Pooling Configuration
---
UniTask is aggressively caching async promise object to achive zero allocation. In default, cache all promises but you can configure `TaskPool.SetMaxPoolSize` to your value, the value indicates cache size per type. `TaskPool.GetCacheSizeInfo` returns current cached object in pool.
```csharp
foreach (var (type, size) in TaskPool.GetCacheSizeInfo())
{
Debug.Log(type + ":" + size);
}
```
2020-06-11 16:44:22 +08:00
> In UnityEditor profiler shows allocation of compiler generated AsyncStateMachine but it only occurs in debug(development) build. C# Compiler generate AsyncStateMachine as class on Debug build and as struct on Release build.
2020-06-09 13:52:04 +08:00
UniTaskSynchronizationContext
---
Unity's default SynchronizationContext(`UnitySynchronizationContext`) is poor implementation for performance. UniTask itself is bypass `SynchronizationContext`(and `ExecutionContext`) so does not use it but if exists in `async Task`, still used it. `UniTaskSynchronizationContext` is replacement of `UnitySynchronizationContext`, it is better for performance.
```csharp
public class SyncContextInjecter
{
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
public static void Inject()
{
SynchronizationContext.SetSynchronizationContext(new UniTaskSynchronizationContext());
}
}
```
This is an optional choice and is not always recommended; `UniTaskSynchronizationContext` is less performance than `async UniTask` and is not a complete UniTask replacement. It also does not guarantee full behavioral compatibility with the `UnitySynchronizationContext`.
2020-06-04 13:52:42 +08:00
API References
2019-06-06 10:53:07 +08:00
---
2020-06-04 13:52:42 +08:00
UniTask's API References is hosted at [cysharp.github.io/UniTask](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.html) by [DocFX](https://dotnet.github.io/docfx/) and [Cysharp/DocfXTemplate](https://github.com/Cysharp/DocfxTemplate).
For example, UniTask's factory methods can see at [UniTask#methods](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.UniTask.html#methods-1). UniTaskAsyncEnumerable's factory/extension methods can see at [UniTaskAsyncEnumerable#methods](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.Linq.UniTaskAsyncEnumerable.html#methods-1).
2019-06-06 10:53:07 +08:00
2020-04-16 19:26:57 +08:00
UPM Package
---
2020-06-04 13:52:42 +08:00
### Install via git URL
After Unity 2019.3.4f1, Unity 2020.1a21, that support path query parameter of git package. You can add `https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask` to Package Manager
2020-04-16 19:26:57 +08:00
![image](https://user-images.githubusercontent.com/46207/79450714-3aadd100-8020-11ea-8aae-b8d87fc4d7be.png)
2020-06-04 13:52:42 +08:00
![image](https://user-images.githubusercontent.com/46207/83702872-e0f17c80-a648-11ea-8183-7469dcd4f810.png)
or add `"com.cysharp.unitask": "https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask"` to `Packages/manifest.json`.
2020-07-04 05:36:14 +08:00
If you want to set a target version, UniTask is using `*.*.*` release tag so you can specify a version like `#2.0.24`. For example `https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.0.24`.
2020-04-16 19:26:57 +08:00
2020-06-04 13:52:42 +08:00
### Install via OpenUPM
2020-04-16 19:26:57 +08:00
2020-06-04 13:52:42 +08:00
The package is available on the [openupm registry](https://openupm.com). It's recommended to install it via [openupm-cli](https://github.com/openupm/openupm-cli).
```
openupm add com.cysharp.unitask
```
2020-04-17 10:15:15 +08:00
2020-06-04 13:52:42 +08:00
.NET Core
2020-05-19 02:33:44 +08:00
---
2020-06-04 13:52:42 +08:00
For .NET Core, use NuGet.
> PM> Install-Package [UniTask](https://www.nuget.org/packages/UniTask)
UniTask of .NET Core version is a subset of Unity UniTask, removed PlayerLoop dependent methods.
It runs at higher performance than the standard Task/ValueTask, but you should be careful to ignore the ExecutionContext/SynchronizationContext when using it. `AysncLocal` also does not work because it ignores ExecutionContext.
If you use UniTask internally, but provide ValueTask as an external API, you can write like the following(Inspired by [PooledAwait](https://github.com/mgravell/PooledAwait)).
2020-05-19 02:33:44 +08:00
```csharp
2020-06-04 13:52:42 +08:00
public class ZeroAllocAsyncAwaitInDotNetCore
{
public ValueTask<int> DoAsync(int x, int y)
{
return Core(this, x, y);
static async UniTask<int> Core(ZeroAllocAsyncAwaitInDotNetCore self, int x, int y)
{
// do anything...
await Task.Delay(TimeSpan.FromSeconds(x + y));
await UniTask.Yield();
return 10;
}
}
}
2020-06-08 00:50:20 +08:00
// UniTask does not return to original SynchronizationContext but you can use helper `ReturnToCurrentSynchronizationContext`.
public ValueTask TestAsync()
{
await using (UniTask.ReturnToCurrentSynchronizationContext())
{
await UniTask.SwitchToThreadPool();
// do anything..
}
}
2020-05-19 02:33:44 +08:00
```
2020-06-04 13:52:42 +08:00
.NET Core version is intended to allow users to use UniTask as an interface when sharing code with Unity (such as [Cysharp/MagicOnion](https://github.com/Cysharp/MagicOnion/)). .NET Core version of UniTask enables smooth code sharing.
Utility methods such as WhenAll which is equivalent to UniTask are provided as [Cysharp/ValueTaskSupplement](https://github.com/Cysharp/ValueTaskSupplement).
2019-06-06 10:53:07 +08:00
License
---
2020-06-04 14:31:42 +08:00
This library is under the MIT License.