UniTask と CancellationToken を使った非同期処理��
最終更新：
orika_ex_miyako 2024年12月30日(月) 16:28:35履歴
非同期処理とは 
非同期処理は、プログラムが複数のタスクを並列に処理する手法の一つです。
例えば、重い処理を行うタスクを別のスレッドで実行し、メインスレッドはユーザーインターフェースの更新などに専念するといった使い方があります。
これにより、プログラムの応答性を保ちつつ、効率的に複数のタスクを進行させることができます。
コルーチン
Unityでは、非同期処理の一つとしてコルーチンがあります。
コルーチンは、特定の時間だけ処理を中断したり、特定の条件が満たされるまで待機したりすることができます。
次のサンプルは、コルーチンを用いて1秒待機する処理です。
using System.Collections;
using UnityEngine;
public class CoroutineExample : MonoBehaviour
{
private void Start()
{
StartCoroutine(WaitAndPrint());
}
private IEnumerator WaitAndPrint()
{
yield return new WaitForSeconds(1);
Debug.Log("Hello after 1 second!");
}
}
UniTaskとは
UniTaskは、Unity向けの非同期処理ライブラリで、Unityのコルーチンをより効率的かつ便利に使うことができます。
特に、async/awaitパターンを活用することで、非同期のロジックを直感的に記述することができます。
UniTaskを使ったコルーチン処理の置き換え
以下は、UniTaskを使った基本的な非同期処理の例です。
ただし、いきなり UniTask と言われても混乱しますので、まずはコルーチンの処理を作成し、
そちらと同じ処理になる形で UniTask に置き換えるようにします。
＜コルーチンの場合＞
using System.Collections;
using UnityEngine;
public class CoroutineExample : MonoBehaviour
{
private void Start()
{
StartCoroutine(Process1());
}
private IEnumerator Process1()
{
yield return new WaitForSeconds(1f);
Debug.Log("Process1 finished!");
StartCoroutine(Process2());
}
private IEnumerator Process2()
{
yield return new WaitUntil(() => Input.GetButtonDown("Fire1"));
Debug.Log("Process2 finished!");
StartCoroutine(Process3());
}
private IEnumerator Process3()
{
yield return new WaitForSeconds(1f);
Debug.Log("Process3 finished!");
}
}
このコードでは、StartメソッドでProcess1コルーチンを開始します。
そのコルーチンが完了したらProcess2コルーチンを開始し、さらにその完了後にProcess3コルーチンを開始します。
＜UniTask の場合＞
上記のコルーチンの処理を同じ内容で UniTask で置き換えた場合のサンプルコードです。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskExample : MonoBehaviour
{
private async void Start()
{
await Process1();
await Process2();
await Process3();
}
private async UniTask Process1()
{
await UniTask.Delay(1000);
Debug.Log("Process1 finished!");
}
private async UniTask Process2()
{
await UniTask.WaitUntil(() => Input.GetButtonDown("Fire1"));
Debug.Log("Process2 finished!");
}
private async UniTask Process3()
{
await UniTask.DelayFrame(60);
Debug.Log("Process3 finished!");
}
}
このコードでは、Process1(), Process2(), Process3()の3つの非同期タスクが順番に実行されます。
それぞれのタスクはUniTaskを返し、awaitキーワードを使ってそのタスクが完了するまで待つことができます。
UniTaskにはUniTask.WaitUntil()メソッドが用意されており、コルーチンで利用している yield return new WaitUntil() と同様の機能を提供します。
コルーチンと UniTask の比較
それぞれの特徴を元に比較してみましょう。
| 特徴 | コルーチン | UniTask |
| 柔軟性 | MonoBehaviour に依存する(継承していないと使えない) | MonoBehaviour 依存なし (クラス単体でも利用可能) |
| 破棄 | ゲームオブジェクトの破壊・非アクティブ状態で停止する | ゲームオブジェクトの破壊・非アクティブ状態でも停止しない |
| キャンセル | StopCoroutine による制御 | CancellationToken による制御 |
| パフォーマンス | 状況に応じて GC(ガベージコレクション) 発生 | GC 削減、効率的 |
| 例外処理 | try-catch が難しい | 標準的な try-catch が利用可能 |
| デバッグのしやすさ | 限定的 (スタックトレース取得困難) | スタックトレースやエラーログが取得しやすい |
| アドレス指定対応 | Addressables 非対応 | Addressables 対応 (非同期インスタンス管理) |
UniTask は MonoBehaviour クラスを継承していないクラスでも利用が可能であり、Addressables にも対応しています。
ただし、ゲームオブジェクトが破棄されても処理が止まらないため、キャンセル処理を検討して用意する必要があります。
特に間違えやすい点として、コルーチンは処理を待機させずに次の処理へ移行する非同期処理であるのに対し、
UniTask を利用した async/await の非同期処理は、待機を前提とした非同期処理である部分です。
コルーチンメソッドを待機させるには、下記のように記述します。
yield return StartCorouine(コルーチンメソッド());
UniTask の場合、上記の処理が基本の非同期処理となっています。
普段のコルーチンメソッドは、yield return をつけないで書くこともあると思いますので、
コルーチンと同じ感覚で UniTask の処理を書いてしまうと、今までとは逆の処理の運用となります。
UniTaskとCancellationToken
CancellationToken(キャンセレーション・トークン)は、非同期タスクのキャンセルを行うための仕組みです。
一度キャンセルされたCancellationTokenは再利用できないため、新たな非同期タスクを開始するたびに新しいCancellationTokenを作成する必要があります。
以下に、CancellationTokenを利用したUniTaskの例を示します：
using Cysharp.Threading.Tasks;
using UnityEngine;
using System.Threading;
public class UniTaskCancellationTokenExample : MonoBehaviour
{
public GameObject button;
public GameObject cancelButton;
private CancellationTokenSource cancellationTokenSource;
private async void Start()
{
using (cancellationTokenSource = new CancellationTokenSource())
{
await WaitUntilButtonPressed();
}
}
private async UniTask WaitUntilButtonPressed()
{
try
{
await UniTask.WaitUntil(() => button.GetComponent<Button>().IsPressed(), cancellationToken: cancellationTokenSource.Token);
Debug.Log("Button pressed!");
}
catch (OperationCanceledException)
{
Debug.Log("Waiting for button press cancelled!");
}
}
public void OnCancelButtonPressed()
{
cancellationTokenSource.Cancel();
}
}
このコードでは、WaitUntilButtonPressedメソッドがボタンが押されるのを待つ非同期タスクを作成します。
そして、そのタスクが完了するまでawaitキーワードを使って待ちます。ボタンが押されたら、メッセージがログに出力されます。
また、キャンセルボタンが押されたら、OnCancelButtonPressedメソッドが呼ばれ、CancellationTokenSourceのCancelメソッドが呼び出されます。
これにより、WaitUntilButtonPressedメソッドの非同期タスクがキャンセルされ、キャンセルが発生したことがログに出力されます。
それでは、先ほど提示したコルーチンの処理を UniTask に置き換えたサンプルコードにも CancellationToken を適用してみましょう。
UniTask で用意されているメソッドには、CancellationToken を指定することが出来るようになっています(デフォルト引数は null です)。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskExample : MonoBehaviour
{
private CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
private async void Start()
{
await Process1();
await Process2();
await Process3();
}
private async UniTask Process1()
{
await UniTask.Delay(1000, cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process1 finished!");
}
private async UniTask Process2()
{
await UniTask.WaitUntil(() => Input.GetButtonDown("Fire1"), cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process2 finished!");
}
private async UniTask Process3()
{
await UniTask.DelayFrame(60, cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process3 finished!");
}
public void CancelAllProcesses()
{
cancellationTokenSource.Cancel();
}
}
このコードでは、各非同期処理にCancellationTokenを適用しています。
そして、CancelAllProcessesメソッドが呼ばれると、すべての非同期処理がキャンセルされます。
UniTaskを用いた非同期処理のエラーハンドリング
非同期処理では、例外が発生する可能性が常に存在します。
この場合、いくつかの方法を利用して、例外を適切にハンドリングすることが重要です。
特に CancellationTokenがキャンセルされたときはOperationCanceledExceptionがスローされますので、ハンドリングしていないとエラーとして停止してしまいます。
以下に、非同期処理のエラーハンドリングの例を示します
１，try/catchブロックを使用した例
最も一般的な方法です。
try/catch(必要に応じて finally)ブロックを使用して、例外のハンドリングを行います。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskErrorHandlingExample : MonoBehaviour
{
private async void Start()
{
try
{
await Process();
}
catch (System.Exception e)
{
Debug.Log("An error occurred: " + e.Message);
}
}
private async UniTask Process()
{
// Here, something might throw an exception...
}
}
このコードでは、Process()メソッドが何らかの例外をスローする可能性があります。
そのため、Process()メソッドの呼び出しはtryブロック内に置かれています。
もしProcess()メソッドが例外をスローしたら、それはcatchブロックで捕捉され、エラーメッセージがログに出力されます。
それでは、先ほど提示したコルーチンの処理を UniTask に置き換えたサンプルコードにもエラーハンドリングを適用してみましょう。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskExample : MonoBehaviour
{
private CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
private async void Start()
{
try
{
await Process1();
await Process2();
await Process3();
}
catch (OperationCanceledException)
{
Debug.Log("Task was cancelled!");
}
}
private async UniTask Process1()
{
await UniTask.Delay(1000, cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process1 finished!");
}
private async UniTask Process2()
{
await UniTask.WaitUntil(() => Input.GetButtonDown("Fire1"), cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process2 finished!");
}
private async UniTask Process3()
{
await UniTask.DelayFrame(60, cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process3 finished!");
}
public void CancelAllProcesses()
{
cancellationTokenSource.Cancel();
}
}
このコードでは、各非同期処理にCancellationTokenを適用しています。
そして、CancelAllProcessesメソッドが呼ばれると、すべての非同期処理がキャンセルされます。
そこで、Startメソッドで非同期処理をawaitする際は、キャンセルが発生した場合に備えてtry/catchブロックで囲んでいます。
これにより、非同期処理がキャンセルされた場合でも適切に処理できます。
２．SuppressCancellationThrow メソッドを利用した方法
先ほどの各プロセスの呼び出しに .SuppressCancellationThrow() を追加しました。
これにより、キャンセルされた場合でも例外がスローされず、処理が正常終了したかのように扱われます。
よって catchブロックは不要 になりますので、キャンセル例外を抑制することで例外が発生しないため、try-catch は削除しました。
各プロセスがキャンセルされた場合、ログ出力は行われませんが、最後に「All processes completed or cancelled.」というメッセージを出力します。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskExample : MonoBehaviour
{
private CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
private async void Start()
{
// SuppressCancellationThrow を使用してキャンセル例外を抑制
await Process1().SuppressCancellationThrow();
await Process2().SuppressCancellationThrow();
await Process3().SuppressCancellationThrow();
Debug.Log("All processes completed or cancelled.");
}
private async UniTask Process1()
{
await UniTask.Delay(1000, cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process1 finished!");
}
private async UniTask Process2()
{
await UniTask.WaitUntil(() => Input.GetButtonDown("Fire1"), cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process2 finished!");
}
private async UniTask Process3()
{
await UniTask.DelayFrame(60, cancellationToken: cancellationTokenSource.Token);
Debug.Log("Process3 finished!");
}
public void CancelAllProcesses()
{
cancellationTokenSource.Cancel();
}
}
ただし、SuppressCancellationThrow() を使うと例外が無視されるため、キャンセル処理を特別に区別する必要がある場合は別途フラグ管理などが必要です。
そちらもまとめておきます。
SuppressCancellationThrow() を使って await とともに呼び出す場合、
UniTask を返すメソッドに対してキャンセルの状態をチェックするためにフラグ（例えば isCancelled）を管理することができます。
このケースにおいて、UniTask.Delay を使用する処理に SuppressCancellationThrow() を追加する形にすると、
キャンセルされたかどうかを追跡する方法を以下のように示すことができます。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskExample : MonoBehaviour
{
private CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
private async void Start()
{
// Process1を呼び出してキャンセル状態を確認
var isCancelled = await Process1(cancellationTokenSource.Token);
if (isCancelled)
{
Debug.Log("Process1 was cancelled.");
}
else
{
Debug.Log("Process1 finished.");
}
// 他のプロセスも同様に処理
var isCancelled2 = await Process2(cancellationTokenSource.Token);
if (isCancelled2)
{
Debug.Log("Process2 was cancelled.");
}
else
{
Debug.Log("Process2 finished.");
}
var isCancelled3 = await Process3(cancellationTokenSource.Token);
if (isCancelled3)
{
Debug.Log("Process3 was cancelled.");
}
else
{
Debug.Log("Process3 finished.");
}
}
private async UniTask<bool> Process1(CancellationToken token)
{
await UniTask.Delay(1000, cancellationToken: token).SuppressCancellationThrow();
return token.IsCancellationRequested; // キャンセルされた場合はtrueを返す
}
private async UniTask<bool> Process2(CancellationToken token)
{
await UniTask.WaitUntil(() => Input.GetButtonDown("Fire1"), cancellationToken: token).SuppressCancellationThrow();
return token.IsCancellationRequested; // キャンセルされた場合はtrueを返す
}
private async UniTask<bool> Process3(CancellationToken token)
{
await UniTask.DelayFrame(60, cancellationToken: token).SuppressCancellationThrow();
return token.IsCancellationRequested; // キャンセルされた場合はtrueを返す
}
public void CancelAllProcesses()
{
cancellationTokenSource.Cancel();
}
}
Process1, Process2, Process3 メソッドが UniTask<bool> を返すように変更され、キャンセル状態（true または false）を返すようになっています。
SuppressCancellationThrow() を使用してキャンセルされた場合でも例外をスローせずに進行します。
各プロセスが終了した後、token.IsCancellationRequested をチェックしてキャンセルされたかどうかを確認し、その状態に基づいてメッセージを出力しています。
以上のことから、SuppressCancellationThrow() を使うことでキャンセル例外を抑制し、token.IsCancellationRequested を利用してキャンセルの状態を追跡できます。
これにより、キャンセルされたかどうかをメソッド内で確認し、呼び出し元で適切に処理を行うことができます。
３．併用する場合
try / catch 処理と SuppressCancellationThrow() メソッドの両方を利用することで、キャンセル発生時のハンドリングと
エラーによる例外処理のハンドリングの両方を分けて判断することが可能です。
using Cysharp.Threading.Tasks;
using UnityEngine;
public class UniTaskExample : MonoBehaviour
{
private CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
private async void Start()
{
try
{
// Process1 を呼び出し、キャンセル状態でエラーハンドリング
await Process1(cancellationTokenSource.Token);
Debug.Log("Process1 finished.");
// 他のプロセスも呼び出し
await Process2(cancellationTokenSource.Token);
Debug.Log("Process2 finished.");
await Process3(cancellationTokenSource.Token);
Debug.Log("Process3 finished.");
}
catch (OperationCanceledException)
{
Debug.Log("One of the processes was cancelled.");
}
}
private async UniTask Process1(CancellationToken token)
{
await UniTask.Delay(1000, cancellationToken: token).SuppressCancellationThrow();
}
private async UniTask Process2(CancellationToken token)
{
await UniTask.WaitUntil(() => Input.GetButtonDown("Fire1"), cancellationToken: token).SuppressCancellationThrow();
}
private async UniTask Process3(CancellationToken token)
{
await UniTask.DelayFrame(60, cancellationToken: token).SuppressCancellationThrow();
}
public void CancelAllProcesses()
{
cancellationTokenSource.Cancel();
}
}
SuppressCancellationThrow() を使うことで例外が発生しないため、catch (OperationCanceledException) で一度だけキャンセルされた場合のエラーハンドリングを行っています。
各 Process メソッドは例外をスローせず、キャンセルされた場合でも処理が続きます。
SuppressCancellationThrow() がキャンセルを無視して例外を投げないようにしますが、try-catch でその状態を適切に捕捉します。
よって冗長なキャンセル状態チェックを行わず、エラー（キャンセル）のみを捕捉してログを表示することで、エラーハンドリングの簡素化を行っています。
try-catch によって、キャンセルが発生した場合のみ適切にハンドリングされ、その他のエラーはそのまま処理が進みます。
SuppressCancellationThrow() を使うことで、キャンセル例外がスローされないため、try-catch でキャンセルを処理する形にして、コードをシンプルに保っています。
この方法で、冗長性を排除し、エラーハンドリングを効率化できます。
UniTaskとDOTween
UniTaskはDOTweenとも連携が可能で、非同期にTweenを待つことができます。
また CancellationToken も指定し、エラーハンドリングすることが出来ます。
以下にその例を示します。
using Cysharp.Threading.Tasks;
using UnityEngine;
using DG.Tweening;
public class UniTaskDOTweenExample : MonoBehaviour
{
public GameObject target;
private async void Start()
{
var token = this.GetCancellationTokenOnDestroy();
try
{
await target.transform.DOMove(new Vector3(10, 0, 0), 1).ToUniTask(cancellationToken: token);
Debug.Log("Move completed!");
}
catch (OperationCanceledException)
{
Debug.Log("Move cancelled!");
}
}
}
このコードでは、対象のオブジェクトを新しい位置に移動させるTweenを作成し、そのTweenが完了するまで非同期に待つことができます。
GetCancellationTokenOnDestroyメソッドを使って、このゲームオブジェクトが破棄されたときに自動的に非同期タスクがキャンセルされるようにしています。
DOTween のようにゲームオブジェクトの挙動に紐づいている処理については、
ゲームオブジェクトの破棄のタイミングで非同期処理がキャンセルされる GetCancellationTokenOnDestroyメソッドを CancellationToken に適用すると便利です。
また Unity 2022.2 以降であれば、destroyCancellationToken 変数を利用しても同じようにキャンセル可能です。
Unity 公式スクリプトリファレンス
MonoBehaviour.destroyCancellationToken
https://docs.unity3d.com/ja/current/ScriptReferenc...
今回提示している DOTween の待機処理ですが
await target.transform.DOMove(new Vector3(10, 0, 0), 1).ToUniTask(cancellationToken: token);
以下の書式でも同じ処理を実装出来ます。
＜別パターン� �
await target.DOMove(new Vector3(10, 0, 0), 1).AsyncWaitForCompletion(cancellationToken: token);
＜別パターン�◆�
Tween tween = target.DOMove(new Vector3(10, 0, 0), 1);
await tween.ToUniTask(cancellationToken: token);
複数の書式がある場合、記述に一貫性を持たせることができればどの処理を利用しても問題ありません。
２．SuppressCancellationThrow メソッドを利用した場合
DOTween の対象(target 変数の値)が安全性が保証されている場合、try / catch の代わりに SuppressCancellationThrow メソッドを利用してキャンセル対応が可能です。
using Cysharp.Threading.Tasks;
using UnityEngine;
using DG.Tweening;
public class UniTaskDOTweenExample : MonoBehaviour
{
public GameObject target;
private async void Start()
{
var token = this.GetCancellationTokenOnDestroy();
// SuppressCancellationThrow を利用してエラーハンドリングをシンプルに
bool isCanceled = await target.transform.DOMove(new Vector3(10, 0, 0), 1)
.ToUniTask(cancellationToken: token)
.SuppressCancellationThrow();
// キャンセルが発生した場合
if (isCanceled)
{
Debug.Log("Move cancelled!");
// TODO キャンセル時の例外処理を書き、必要に応じて return などを講じる
}
}
}
万が一キャンセルが発生しても例外処理は発生しませんので、catch は不要です。
３．併用する場合
もしも DOTween の対象(target 変数の値)の安全性の担保が難しい場合には、
try / catch と SuppressCancellationThrow メソッドを合わせて記述することで
キャンセル発生時、およびエラー発生時の例外処理のハンドリングが行えます。
using Cysharp.Threading.Tasks;
using UnityEngine;
using DG.Tweening;
public class UniTaskDOTweenExample : MonoBehaviour
{
public GameObject target;
private async void Start()
{
var token = this.GetCancellationTokenOnDestroy();
try
{
// キャンセル例外抑制 + キャンセル状態を直接判定
var isCanceled = await target.transform.DOMove(new Vector3(10, 0, 0), 1)
.ToUniTask(cancellationToken: token)
.SuppressCancellationThrow();
// キャンセル状態の判定
if (isCanceled)
{
Debug.Log("Move cancelled!");
}
else
{
Debug.Log("Move completed!");
}
}
catch (Exception ex)
{
// 通常のエラー処理
Debug.LogError($"An error occurred: {ex.Message}");
}
}
}
キャンセルは SuppressCancellationThrow メソッドの戻り値で判定し、例外は通常の try-catch で処理します。これにより、キャンセルとエラーを明確に分けて管理できます。
UniTask 利用の注意点
コルーチンの処理とは処理構造的に異なるため、同じように記述しても、想定している通りに動かないケースがあります。
await = yield return StartCoroutine の置き換えを念頭におき、yield return なしの StartCoroutine の場合には await を使わずに Forget メソッドを適用するようにして対応してください。
UniTask のエラーハンドリングには、例外発生時のスタックトレースを記述してください。
UniTask.Void の利用は慎重に行い、Forget() を使う場合は例外処理を組み込んでください。
そして CancellationToken を適切に扱い、処理のキャンセルを確認するテストケースを用意しましょう。
UniTask の利用は効率的ですが、適切にキャンセル処理を管理しないとメモリリークの原因となります。
また、Addressables 使用時はアセットのリリース処理も忘れずに実装しましょう。
まとめ
この記事では、UniTaskを用いたUnityでの非同期処理の基礎について解説しました。
UniTaskを使用することで、コルーチンの管理がより容易になり、コードも直感的になります。
CancellationTokenを用いて非同期処理をキャンセルする方法や、DOTweenとの連携方法についても説明しました。
非同期処理はUnityのパフォーマンスを向上させる強力なツールであり、UniTaskはその実装を助ける重要なライブラリです。
しかし、非同期処理は例外をうまくハンドリングすることが求められるため、エラーハンドリングの処理を適切に使用することを忘れないでください。
参考サイト
参考にさせていただきました。ありがとうございました。
Qiita @IShix 様
【Unity】UniTask Coroutineとの違いとキャンセル処理の挙動
https://qiita.com/IShix/items/dcf86cb5ca1b587a88ad
はなちるのマイノート 様
【UniTask】SuppressCancellationThrowを使ってキャンセルを返り値として取り出す
https://www.hanachiru-blog.com/entry/2021/07/01/22...
ゆるユニ 様
【Unity】分かりやすいUniTaskのキャンセル方法まとめ！
https://yuru-uni.com/2024/04/06/unitask_cancel/
コメントをかく