Async

A "fiber" / green-thread handle: an in-flight Async that is being driven eagerly, can be Cancelable.cancelled, and can be Pollable.poll ed to observe (or join) its outcome. A Running is itself an Async[A].

Sequentially run as and collect their values into a List in input order. A failure short-circuits — subsequent inputs are not driven and the failure is propagated.

Create a failed Async carrying cause. A failed value short-circuits map / flatMap without invoking the continuation, is recoverable with .catchAll, and is re-thrown by .block.

Create a reusable fair selector over inputs.

A selector owns one running observation of each input. Each successful AsyncSelector.select removes its winning slot; call AsyncSelector.replace to arm that slot again. The scan starts after the previous winner, so a continuously-ready slot is selected within at most the number of currently armed slots selections. Shutting down the selector cancels every armed loser and joins all of their cleanup.

Evaluate body on a background worker (JVM) or microtask (JS) and return a Running for the result — the Async analogue of Future.apply.

A single by-name entry point (no by-value overload): the worker evaluates body, capturing a throw — including a statically Nothing-typed body (Async.start { ...; throw e }, Async.start(???)) — as a failed run rather than letting it escape at the call site, and lifts the result with the same runtime encoding as every other value received from the user (a Pollable success value is wrapped, a AsyncEncoding.WrappedPollable carrier has its depth incremented).

To eagerly drive an '''already-built''' Async instead — composing with either, tap, foldCause, ... before driving (e.g. fa.either.tap(record).start) — use the fa.start extension method. A Running is itself an Async[A] and may be polled, Cancelable.cancel led (a no-op once completed), or further composed; on the JVM a suspended run proceeds on a background worker, on Scala.js via microtasks.

Lift an already-available value into a successful Async.

The value may itself be an Async (or a Pollable): such a value is carried as '''data''', one nesting level at a time — map/flatMap continuations, .block, and the drivers deliver it unwrapped exactly one layer per delivery (flatten peels one level), never silently running it as a computation. Sequencing effects is flatMap's job; reach for nesting only when an effect value is genuinely the payload.

Direct-style await block. Inside body, callers may write .await on any Async[X] to extract its value without blocking; the body returns the final A, which becomes the resulting Async[A]. Exceptions thrown by the body — including the rethrow from a .await of a failed Async — surface as Async.fail. Awaits run in source order.

.await is lexically restricted to this block — using it anywhere else is a compile error.

'''Evaluation is eager up to the first pending suspension''' (see the "Evaluation model" docs): the synchronous prefix and any ready .awaits run at construction. At a genuinely pending .await the platforms diverge by design — on the JVM (and Scala.js < 3.8) the continuation runs only when the result is driven (.block / fa.start / interop), while the Scala.js 3.8+ native js.async/js.await arm self-resumes it off the event loop. The delivered value is identical everywhere.

Evaluate body eagerly, capturing any thrown Throwable as a failed Async (see Async.fail). The standard way to bridge throw-based code into Async so that .catchAll can recover the error.

inline so body is spliced directly into the try at the call site: unlike a by-name body: => A parameter, no Function0 thunk is allocated (the JVM's escape analysis usually scalar-replaces such a thunk on a hot monomorphic path anyway, but inlining removes it unconditionally — including on cold, megamorphic, and code-generated call sites such as a no-await Async.async { ... }).

Note: attempt catches every Throwable, with no non-fatal/fatal distinction. Callers who want fatal errors to propagate should rethrow them from their recovery handler.

Construct an Async that completes with the same value or error as stage.

Construct an Async that completes with the same value or error as future. No ExecutionContext is required.

Create an Async completed by body, which is given a Completer to succeed or fail. If the body completes the completer before returning, the result is already completed; otherwise it remains pending until the completer is completed (e.g. from a callback).

An Async that never completes. Useful as a sentinel in tests and as the right-zero of orElse-style operations.