You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.MD
+14-10Lines changed: 14 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,9 @@ void Start()
61
61
62
62
...
63
63
```
64
-
Easy-peasy, right? WaitForFrames is an `IAwaitInstruction`. When you await it, it spawns a `Continuation<T>`, which is (automatically) inserted into a queue and evaluated every frame until it is finished; in this case it will take one frame. We could return Task instead of void if we wanted to store the coroutine.
64
+
Easy-peasy, right? WaitForFrames is an `IAwaitInstruction`. When you await it, it spawns a `Continuation<T>`, which is (automatically) inserted into a queue and evaluated every frame until it is finished; in this case it will take one frame. Once finished, whatever is after the `IAwaitInstruction` is invoked. We could return `Task` instead of `void` if we wanted to store the coroutine for nesting.
65
+
66
+
If you want to link the lifetime of an async coroutine (or part of the coroutine) to a `UnityEngine.Object`, like the built-in `Coroutine`s do, see the ConfigureAwait section.
65
67
66
68
## Returning a result
67
69
Let's say we have some work we want to perform across the main thread, but it's too much to perform in a single frame. We can create a coroutine for this and return the result of the work once it is finished.
@@ -126,7 +128,7 @@ async void Start()
126
128
`Await` actually contains many shortcut functions to streamline your code.
127
129
128
130
## ConfigureAwait
129
-
Just like with `Task`s, UnityAsync `Continuation<T>`s can be configured. You can set the scheduler (Update, LateUpdate, FixedUpdate) and also link its lifespan to a `UnityEngine.Object` or `CancellationToken`.
131
+
Just like with `Task`s, UnityAsync `Continuation<T>`s can be configured. You can set the scheduler (Update, LateUpdate, FixedUpdate) and also link its lifespan to a `UnityEngine.Object` or `CancellationToken`. Anything after the `await` line will not be reached if the `Continuation` was cancelled (either by its linked `UnityEngine.Object` being destroyed or a cancellation requested on the token.
// ...we are now in fixed update (assuming this MonoBehaviour was not destroyed)
145
147
}
146
148
147
149
...
@@ -181,23 +183,25 @@ Built-in:
181
183
*`WaitForFrames`
182
184
*`WaitForSeconds`
183
185
*`WaitForUnscaledSeconds`
184
-
*`WaitUntil`
185
-
*`WaitWhile`
186
+
*`WaitUntil`<sup>1</sup>
187
+
*`WaitWhile`<sup>1</sup>
186
188
187
189
Unity:
188
-
*`IEnumerator`*
189
-
*`YieldInstruction`*
190
+
*`IEnumerator`<sup>2</sup>
191
+
*`YieldInstruction`<sup>2</sup>
190
192
*`AsyncOperation`
191
-
*`ResourceRequest`**
193
+
*`ResourceRequest`<sup>3</sup>
192
194
193
195
Others:
194
196
*`Task`
195
197
*`Task<>`
196
198
* …anything that implements `GetAwaiter()`
197
199
198
-
*Will spin up a Unity `Coroutine`, causing allocations.
200
+
<sup>1</sup>May cause a delegate closure.
201
+
202
+
<sup>2</sup>Will spin up a Unity `Coroutine`, causing allocations.
199
203
200
-
**Very small delegate allocation.
204
+
<sup>3</sup>Very small delegate allocation.
201
205
202
206
Anything that implements `IAwaitInstruction` can be awaited and will be evaluated in Update, LateUpdate, or FixedUpdate. This is how the built-in await instructions are implemented. The advantage over `Task`s or `CustomYieldInstruction`s is they don't cause any allocations if implemented as structs.
0 commit comments