Skip to content

Commit a07de3f

Browse files
authored
Update README.MD
1 parent a19f812 commit a07de3f

File tree

1 file changed

+14
-10
lines changed

1 file changed

+14
-10
lines changed

README.MD

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,9 @@ void Start()
6161

6262
...
6363
```
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.
6567

6668
## Returning a result
6769
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()
126128
`Await` actually contains many shortcut functions to streamline your code.
127129

128130
## 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.
130132
```c#
131133
using UnityEngine;
132134
using UnityAsync;
@@ -141,7 +143,7 @@ async void Start()
141143
// time is evaluated every fixed update
142144
await Await.Seconds(10).ConfigureAwait(this, FrameScheduler.FixedUpdate);
143145

144-
// ...we are now in fixed update
146+
// ...we are now in fixed update (assuming this MonoBehaviour was not destroyed)
145147
}
146148

147149
...
@@ -181,23 +183,25 @@ Built-in:
181183
* `WaitForFrames`
182184
* `WaitForSeconds`
183185
* `WaitForUnscaledSeconds`
184-
* `WaitUntil`
185-
* `WaitWhile`
186+
* `WaitUntil`<sup>1</sup>
187+
* `WaitWhile`<sup>1</sup>
186188

187189
Unity:
188-
* `IEnumerator`*
189-
* `YieldInstruction`*
190+
* `IEnumerator`<sup>2</sup>
191+
* `YieldInstruction`<sup>2</sup>
190192
* `AsyncOperation`
191-
* `ResourceRequest`**
193+
* `ResourceRequest`<sup>3</sup>
192194

193195
Others:
194196
* `Task`
195197
* `Task<>`
196198
* …anything that implements `GetAwaiter()`
197199

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.
199203

200-
**Very small delegate allocation.
204+
<sup>3</sup>Very small delegate allocation.
201205

202206
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.
203207
# Custom await instructions

0 commit comments

Comments
 (0)