ScriptReference/Awaitable

[giscus[bot]]

ScriptReference/Awaitable

https://docs.unity3d.com/ScriptReference/Awaitable.html

[vertxxyz]

See Awaitable support in the manual for more information.

This is also a comment taken from the C# reference source (and edited for spelling):

Awaitable Coroutines are async/await compatible types specially tailored for running in Unity. (they can be awaited, and they can be used as return type of an async method)
Compared to System.Threading.Tasks it is much less smart and takes shortcuts to improve performance based on Unity-specific assumptions.
Main differences compared to .NET tasks:

• Can be awaited only once: a given Awaitable object can't be awaited by multiple async functions. This is considered undefined behaviour (considering it undefined behaviour allows for optimizations non-achievable otherwise).
• Never capture an ExecutionContext: for security purposes, .NET Tasks capture execution contexts on awaiting to be able to handle things like propagating impersonation contexts across async calls. We don't want to support that and can eliminate associated costs.
• Never capture Synchronization context:
  Coroutines continuations are run synchronously from the code raising the completion. In most cases, it will be from the Unity main frame (eg. for Delayed Call Coroutines and existing AsyncOperations).
  Methods returning awaitable coroutines with completion being raised in a background thread will need to mention it explicitly in their documentation.
• Awaiter.GetResults won't block until completion. Calling GetResults() before the operation is completed is an undefined behaviour.
• Are pooled object:
  Those are reference types, so that they can be referenced accross different stacks, efficiently copied etc, but to avoid too many allocations, they are pooled. ObjectPool has been enhanced a bit to account to avoid Stack bounds checks with common get/release patterns produced by async state machines
• Can be implemented in either managed or native code:
  There is Scripting::Awaitables::Awaitable base class providing interop with this managed coroutine type, that can be extended so that Native asynchronous code can be exposed as an await-compatible type in user code.
  See AsyncOperationCoroutine implementation as an example