Wait until a context is ready
Wait for a context
A context is ready once all its members are injected, including its
Async members. To wait until a context is ready, use the form that fits your
code:
| Where | Code |
|---|---|
| A coroutine | yield return Context.WhenReady(this); |
An async method | await Context.WhenReady(this); |
| An event handler | Context.WhenReady(this).Completed += operation => ...; |
| Callbacks | Context.WhenReady(this).Subscribe(onSucceeded: ..., onFailed: ...); |
| Code that runs every frame | if (Context.IsReady(this) == false) return; |
If a required member fails, the wait fails too: await throws the exception, Subscribe
calls onFailed, and after yield return, ThrowIfNotSucceeded() throws it.
Context.IsReady stays false for a context whose injection failed.
await throws an exception.In a ScriptableObject, subscribe to Completed in OnEnable. In a plain C# class, subscribe
in the constructor. A handler you add after the operation completed runs at once.
To wait for another context, pass it instead of this. For the static members of a class, pass the class's
Type. If the context is released or destroyed before it's
ready, the wait completes as CanceledOrDetached.
If the context isn't ready within two minutes, the wait fails with a TimeoutException, which names
the likely cause, such as an inactive GameObject or a class from a precompiled DLL that nothing passes to
Manual.Inject. The context itself keeps injecting. To change the limit, pass it in seconds:
yield return Context.WhenReady(panel, 600); // a panel the player may open later
yield return Context.WhenReady(panel, float.PositiveInfinity); // no limit
With 0, the wait fails at once unless the context is already ready. To check without an error, use
Context.IsReady.
Read and control the wait
Context.WhenReady returns a SelvageOperation. So do Manual.Inject,
Manual.Reinject and Manual.Release, which complete once their work is done. An operation
has the following members:
| Member | Description |
|---|---|
Status | Running, Succeeded, CanceledOrDetached or Failed. |
Exception | The failure of a failed operation, otherwise null. |
IsComplete | Whether the operation has finished, whatever its outcome. |
Detach() | Stops waiting now. The operation completes as CanceledOrDetached, but the injection keeps running. To stop the injection, call Manual.Release. |
DetachAfter(seconds) | Stops waiting after a delay, in seconds or as a TimeSpan, without an error: await Context.WhenReady(this).DetachAfter(5); |
Completed, Subscribe(...) | Run code when the operation completes. Subscribe takes one callback per outcome, and returns an action that unsubscribes them. |
ThrowIfNotSucceeded() | Throws the failure of a failed operation, or an OperationCanceledException for a canceled one. |
AsTask() | The operation as a Task, such as for Task.WhenAll. |
SelvageOperation.Combine(...) | One operation that succeeds when all the given operations succeed. |
The following script waits at most 10 seconds for an Async member. A wait that ends without the
context being ready, after the timeout or because the context was released, throws an
OperationCanceledException:
[Inject(Async = true)] ISaveData save;
async void Start()
{
try
{
await Context.WhenReady(this).DetachAfter(10);
ShowBest(save.BestScore);
}
catch (OperationCanceledException)
{
ShowOffline(); // not ready after 10 seconds, or released
}
}
A failed member's exception isn't caught here, so Unity logs it.
When an operation fails and no code reads its outcome (by waiting for it, reading Status or
Exception, or with Subscribe), Selvage logs the failure, so a failure is never silent.