Yield

Static utility class providing frame-synchronous awaitable methods for async/await code running on Unity's main thread. Acts as the primary API for yielding execution back to the ParagonSynchronizationContext, resuming at specific Unity update phases. Also provides Task composition helpers (WhenAll, WhenAny) and cancellation integration via OnBeforeYield / OnAfterYield events.

Definition

Namespace: Paragon.Core.Async Assembly: Paragon.dll

public static class Yield

Remarks

Yield is the primary way game code interacts with the ParagonSynchronizationContext. Instead of using Task.Delay() or Task.Yield() (which do not integrate with Unity's frame loop or the cancellation system), game code uses await Yield.WaitForUpdate(), await Yield.WaitForSeconds(), etc.

Each WaitFor* method:

1. Fires OnBeforeYield — used by CancellableTask to check for cancellation at every yield point.

2. Awaits the appropriate YieldAwaitable — posts the continuation to the ParagonSynchronizationContext for execution at the correct update phase.

3. Fires OnAfterYield — signals that the continuation has resumed.

This event pair is what makes the Action System's CancellableTask work: it hooks OnBeforeYield to call ThrowIfCancellationRequested(), ensuring that every yield point is a potential cancellation checkpoint.

Quick Lookup

Goal	How
Wait one frame (Update)	await Yield.WaitForUpdate()
Wait one frame (LateUpdate)	await Yield.WaitForEndOfFrame()
Wait one frame (FixedUpdate)	await Yield.WaitForFixedUpdate()
Wait N seconds (game time)	await Yield.WaitForSeconds(2f)
Wait until condition is true	await Yield.WaitUntil(() => isReady)
Wait while condition is true	await Yield.WaitWhile(() => isBusy)
Wait one editor frame	await Yield.WaitForEditorUpdate() (Editor only)
Wait N seconds (editor time)	await Yield.WaitForEditorSeconds(2f) (Editor only)
Already-completed task	Yield.CompletedTask
Wait for all tasks	await Yield.WhenAll(task1, task2)
Wait for any task	await Yield.WhenAny(task1, task2)

Properties

CompletedTask

Returns a pre-completed Task. Convenience wrapper around Task.CompletedTask.

public static Task CompletedTask { get; }

Events

OnBeforeYield

Fired immediately before each yield point. Used by CancellableTask to throw OperationCanceledException if cancellation was requested.

public static event Action OnBeforeYield;

OnAfterYield

Fired immediately after the continuation resumes from a yield point.

public static event Action OnAfterYield;

Methods

WaitForUpdate

Yields until the next Update phase.

public static async Task WaitForUpdate()

WaitForFixedUpdate

Yields until the next FixedUpdate phase.

public static async Task WaitForFixedUpdate()

WaitForEndOfFrame

Yields until the next LateUpdate phase.

public static async Task WaitForEndOfFrame()

WaitForEditorUpdate

(Editor only) Yields until the next editor update tick.

public static async Task WaitForEditorUpdate()

WaitForSeconds

Yields across multiple frames until the specified duration (in game time) has elapsed.

public static async Task WaitForSeconds(float seconds)

Parameter	Type	Description
seconds	float	Duration to wait in seconds (uses Time.deltaTime)

Uses Time.deltaTime, so it respects Time.timeScale. Each frame is a cancellation-checked yield point.

WaitForEditorSeconds

(Editor only) Yields across multiple editor ticks until the specified duration (in real editor time) has elapsed.

public static async Task WaitForEditorSeconds(float seconds)

Parameter	Type	Description
seconds	float	Duration to wait in seconds (uses EditorApplication.timeSinceStartup)

WaitWhile

Yields each frame while the predicate returns true. Resumes on the first frame the predicate returns false.

public static async Task WaitWhile(Func<bool> predicate, WorkExecutionTime executionTime = WorkExecutionTime.UPDATE)

Parameter	Type	Description
predicate	Func<bool>	Condition to evaluate each frame
executionTime	WorkExecutionTime	Which update phase to yield at. Default: UPDATE

WaitUntil

Yields each frame until the predicate returns true. Resumes on the first frame the predicate returns true.

public static async Task WaitUntil(Func<bool> predicate, WorkExecutionTime executionTime = WorkExecutionTime.UPDATE)

Parameter	Type	Description
predicate	Func<bool>	Condition to evaluate each frame
executionTime	WorkExecutionTime	Which update phase to yield at. Default: UPDATE

WhenAll

Waits for all provided tasks to complete. Delegates to Task.WhenAll.

public static Task WhenAll(params Task[] tasks)
public static Task WhenAll<TResult>(params Task<TResult>[] tasks)
public static Task WhenAll(IEnumerable<Task> tasks)
public static Task WhenAll<TResult>(IEnumerable<Task<TResult>> tasks)

WhenAny

Waits for any one of the provided tasks to complete. Delegates to Task.WhenAny.

public static Task WhenAny(params Task[] tasks)
public static Task WhenAny<TResult>(params Task<TResult>[] tasks)
public static Task WhenAny(IEnumerable<Task> tasks)
public static Task WhenAny<TResult>(IEnumerable<Task<TResult>> tasks)

Common Pitfalls

Using Task.Delay instead of Yield.WaitForSeconds Task.Delay() does not integrate with the ParagonSynchronizationContext or the CancellableTask cancellation system. It may also resume on a thread pool thread instead of the main thread. Always use Yield.WaitForSeconds().

Using Task.Yield instead of Yield.WaitForUpdate Task.Yield() uses the default SynchronizationContext.Post() path, which goes to the Update runner. While this works, it bypasses the OnBeforeYield / OnAfterYield events, breaking cancellation integration. Use Yield.WaitForUpdate() instead.

WaitForEndOfFrame maps to LateUpdate, not end of frame Despite the name, WaitForEndOfFrame() resumes during LateUpdate, not at the true end of the rendering frame. This matches Unity's coroutine WaitForEndOfFrame behavior in most practical scenarios.

WaitForSeconds respects Time.timeScale Because WaitForSeconds() accumulates Time.deltaTime, pausing the game (setting Time.timeScale = 0) will cause the wait to stall indefinitely. Use WaitForEditorSeconds() in editor contexts or implement a real-time variant if needed.

Examples

Basic Frame Yielding

protected override async Task OnExecute()
{
    Debug.Log("Before yield");
    await Yield.WaitForUpdate();
    Debug.Log("Next frame");
}

Timed Action

protected override async Task OnExecute()
{
    float duration = 3f;
    await Yield.WaitForSeconds(duration);
    Debug.Log($"Waited {duration} seconds");
}

Conditional Waiting

protected override async Task OnExecute()
{
    // Wait until the target is close enough
    await Yield.WaitUntil(() =>
        Vector3.Distance(transform.position, target.position) < 1f);

    Debug.Log("Target reached!");
}

Parallel Tasks

await Yield.WhenAll(
    MoveToPosition(target1),
    PlayAnimation("walk"),
    FadeInUI()
);
Debug.Log("All complete");

See Also

• YieldAwaitable — the awaitable struct that powers Yield methods

• ParagonSynchronizationContext — the synchronization context that executes continuations

• WorkRunner — the queue that runs continuations at the correct update phase

• SynchronizationContext Subsystem — subsystem overview