Async/Await and Tasks

An async function runs synchronously from the caller’s point of view — it does not spawn a new thread by itself — but it may suspend at points marked await, handing the thread back to the system so other work can run while the awaited operation completes; when the awaited value is ready, the function resumes, possibly on a different thread than the one it suspended on. Only another async context can call an async function directly with await; ordinary synchronous code must instead hand off into one, most commonly by creating a Task (see below).

Synchronous code cannot await directly — it has no suspension mechanism of its own — so the standard bridge is to wrap the async call in a Task { }, which starts running immediately and inherits the priority and actor context of the code that created it. The synchronous method returns right away without waiting for the task to finish; see Task and Structured Concurrency below for how a caller instead awaits a task’s result when it needs one.

AsyncSequence is the asynchronous counterpart of Sequence: its next() is async, so producing each element may itself suspend, and for await iterates it exactly like an ordinary for loop iterates a Sequence, except each iteration is itself an await point. AsyncStream (and its throwing counterpart AsyncThrowingStream) gives an off-the-shelf AsyncSequence backed by a continuation that a push-based producer — a delegate callback, a timer, a notification handler — calls into with yield(_:) and finish(), which is the idiomatic way to adapt callback-style APIs into for await without writing a custom AsyncIteratorProtocol conformance.

async let binds the result of an async call to a constant that begins running immediately, concurrently with whatever code follows it, rather than waiting to be awaited the way a plain await on its own line would; the value is only actually awaited — and its result observed, or its error propagated for a throwing call — the first time the constant is used. It is the lightest-weight way to run a small, fixed number of independent async calls in parallel; a dynamic or unbounded number of parallel child tasks instead needs a task group (next).

withTaskGroup(of:body:) and its throwing counterpart withThrowingTaskGroup(of:body:) create a structured scope of child tasks: group.addTask { } spawns each child, they all run concurrently, and the group itself cannot return until every child has either finished or been cancelled — structured concurrency’s core guarantee is that a parent scope can never outlive its children, unlike a bare background thread that can leak past the function that started it. Iterating the group with for await collects each child’s result as it completes, not necessarily in the order the children were added; in the throwing variant, the first child error encountered is rethrown and cancels the remaining children.

Cancellation in Swift’s concurrency model is cooperative: calling cancel() on a task only flags it as cancelled, it does not forcibly stop it — the task’s own code must periodically call Task.checkCancellation() (which throws CancellationError) or read Task.isCancelled and react. withTaskCancellationHandler(operation: onCancel:) additionally registers a synchronous callback that fires as soon as cancellation is requested, useful for releasing an external resource (a socket, a file handle) that the cancelled operation’s own cooperative check might not reach in time.

Task { } creates an unstructured task: unlike a task-group child, it is not tied to the lifetime of any enclosing scope, but it still inherits the priority and actor/isolation context of the code that created it. Task.detached { } goes further and inherits neither — it is the right tool only when a truly independent unit of work is needed, since it forgoes the cancellation propagation and context inheritance that make ordinary Task { } and task groups easier to reason about; prefer structured concurrency (task groups, async let) or a plain Task { } unless detachment is specifically required. Priorities (.high, .userInitiated, .medium, .low, .utility, .background) are hints to the scheduler, not guarantees; a task’s optional name: aids debugging in Instruments and crash reports.

A @TaskLocal static property behaves like thread-local storage adapted to structured concurrency: its value is bound only for the duration of a withValue(_:operation:) scope, and any task — including child tasks — created within that scope inherits the bound value automatically, which makes it well suited for propagating request IDs, trace/span identifiers, or other request-scoped context through a call tree without threading an explicit parameter through every function signature.

withCheckedContinuation(:) and withCheckedThrowingContinuation(:) bridge a completion-handler-based API into async/await by suspending the current task until the continuation’s resume(returning:) / resume(throwing:) / resume(with:) is called from inside the completion handler. The "checked" variants trap at runtime if the continuation is resumed zero times or more than once, which catches the single most common bridging bug during development; withUnsafeContinuation/withUnsafeThrowingContinuation drop that runtime check for a small performance win once the bridging code is proven correct.

The child tasks above run concurrently and complete in whatever order their work actually finishes — here, child 1 finishes first and child 2 last — and for await over the group yields each result in that completion order, not the order addTask added them; the group as a whole cannot return from withTaskGroup until every child, including any still running when an earlier one completes, has finished or been cancelled.

TSPL: Concurrency (Defining and Calling Asynchronous Functions; Asynchronous Sequences; Calling Asynchronous Functions in Parallel; Tasks and Task Groups; Task Cancellation); stdlib → Concurrency.