Manual/async-await-support

[giscus[bot]]

Manual/async-await-support

https://docs.unity3d.com/Manual/async-await-support.html

[QuinnCG]

When cancelling an awaitable method from the Awaitable utility class via it's token, know that Unity will throw an exception: "OperationCanceledException: coroutine canceled".

// If the destroyCancellationToken is raised, cancelling the WaitForSecondsAsync method, then the exception will be throw to the Unity console.
await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);

// While not ideal, one way to avoid this exception being written to the console is to intercept it.
try
{
	await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);
}
catch (OperationCanceledException) { }

Here is a utility class that does that and a bit more:

public static class Wait
{
	public static async Awaitable Duration(float seconds, CancellationToken token = default)
	{
		try
		{
			await Awaitable.WaitForSecondsAsync(seconds, token);
		}
		catch (OperationCanceledException) { }
	}

	public static async Awaitable NextFrame(CancellationToken token = default)
	{
		try
		{
			await Awaitable.NextFrameAsync(token);
		}
		catch (OperationCanceledException) { }
	}
	/// <summary>
		/// Wait for more than 1 frame.
		/// </summary>
	public static async Awaitable NextFrame(int frames, CancellationToken token = default)
	{
		for (int i = 0; i < frames; i++)
		{
			if (token.IsCancellationRequested)
			{
				break;
			}

			await Awaitable.NextFrameAsync(token);
		}
	}

	public static async Awaitable While(Func<bool> predicate, CancellationToken token = default)
	{
		while (!token.IsCancellationRequested && predicate())
		{
			await NextFrame(token);
		}
	}

	public static async Awaitable Until(Func<bool> predicate, CancellationToken token = default)
	{
		while (!token.IsCancellationRequested && !predicate())
		{
			await NextFrame(token);
		}
	}
}

[vertxxyz]

The value of the exception is in the flow control, it should often be thrown completely to the root of your async method stack.
For example, if you're using the destroyCancellationToken then you want the async stack to end when the object is destroyed, not just the single wait being performed. So wrapping the whole top level method in a try-catch and suppressing the OperationCanceledException there is generally appropriate.

Cancellation can also simplify exceptional cases, and there too you wouldn't want to catch inside of a wait, you want to know when the token has been cancelled and respond to it.

Having a wrapper that neuters the exception removes its value and I'd argue that if you were to do that the class or methods should indicate very clearly that that's happening.