Manual

Coroutines

Start, await and yield: run(), go(), await(), and the model they share.

Introduction#

phasync::run starts the first coroutine and returns once every coroutine it started has ended. phasync::go starts another one without waiting for it, and phasync::await waits for one, returning what it returned or throwing what it threw. Every coroutine belongs to a Frame — the particular run() call that is waiting for it, which decides when a cancellation or a failure reaches it. See Scopes and frames for more on that, and Advanced: Coroutines for how coroutines are scheduled.

Concepts#

• Coroutines – How coroutines, frames and cancellation work.
• Threads and concurrency – What runs at the same time, and what only looks like it.
• Design – Why phasync and Swerve are built the way they are.

Examples#

• All examples of this topic – 12 with their output.

Reference#

• phasync – The static API of phasync: start coroutines, wait for them, cancel them, and wait for streams and flags.
• phasync::run – Runs $fn and returns its result once it and every coroutine started inside it have ended.
• phasync::go – Starts $fn as a coroutine in the current frame and scope, and returns it, without waiting for it.
• phasync::await – Waits for a coroutine or a promise, and returns its result or throws the exception it ended with.
• phasync::yield – Suspends the current coroutine until the loop has made its next round, after the coroutines that were ready have run.
• AggregateException – More than one thing failed in one run(): what $fn threw and the failures of coroutines nobody awaited, or several of those.
• RethrowExceptionInterface – Marks the exceptions that phasync rethrows with a stack trace that begins in the code that called phasync, not inside it.