Asynchronous fiber result wrapper

Synopsis

Declared in <folly/fibers/async/Async.h>

template<typename T>
class [[nodiscard]] Async;

Description

Syntactic sugar to indicate that can be used as the return type of a function, indicating that a fiber can be preempted within that function. Wraps the eagerly executed result of the function and must be 'await'ed to retrieve the result.

Since fibers context switches are implicit, it can be difficult to tell if a function does I/O. In large codebases, it can also be difficult to tell if a given function is running on fibers or not. The Async<> return type makes I/O explicit and provides a good way to identify code paths running on fiber.

Async must be combined with static analysis (eg. lints) that forces a function that calls 'await' to also return an Async wrapped result.

Runtime Consideration:

  • The wrapper is currently 0 cost (in optimized builds), and this will remain a guarentee

  • It provides protection (in debug builds) against running Async‐annotated code on main context.

  • It does NOT provide protection against doing I/O in non Async‐annotated code, both asynchronously (on fiber) or blocking (main context).

  • It does NOT provide protection from fiber's stack overflow.

Type Aliases

Name

Description

inner_type

The value type wrapped by this Async.

Member Functions

Name

Description

Async [constructor]

Constructors

operator=

Assignment operators

Specializations

Name

Description

Async<void>

Async wrapper specialization for functions that produce no value.

Deduction Guides

Name

Description

Async<T>

Deduction guide to make it easier to construct and return Async objects. The guide doesn't permit constructing and returning by reference.

Friends

Name

Description

folly::fibers::async::Async

Asynchronous fiber result wrapper

folly::fibers::async::tag_invoke

Awaits the wrapper and returns its stored value.

Non-Member Functions

Name

Description

awaitTry

Await an async‐annotated functor, capturing its result or exception in a Try.

baton_try_wait_for

Async tagged wrapper that waits on a baton for a bounded duration.

baton_try_wait_until

Async tagged wrapper that waits on a baton until a deadline.

collectAll

collectAll version that takes a varying number of functors instead of a container or iterators

collectAll

Schedules several async annotated functors and blocks until all of these are completed. If any of the functors throws an exception, this exception will be re‐thrown, but only when all the tasks are complete. If several throw exceptions one of them will be re‐thrown.

executeOnNewFiber

Run an async‐annotated functor on a new fiber, blocking the current fiber.

executeOnRemoteFiber

Run an async‐annotated functor on a new fiber on remote thread, blocking the current fiber.

executeWithNewRoot

Executes F with a new async‐stack‐root, making it possible to stitch stacks across async hops.

fromTry

Convert a Try into an Async result, rethrowing any stored exception.

futureWait

Async tagged helpers to perform blocking future operations. Ensures that functions that block on futures are annotated as well.

futureWait

Blocks on a Future and returns its value as an Async result.

init_await

A utility to start annotating at top of stack (eg. the task which is added to fiber manager) A function must not return an Async wrapper if it uses init_await instead of await (again, enforce via static analysis)

promiseWait

Async annotated wrapper around fibers::await

taskWait

Block on a task's execution. Should be called from an Async annotated function. The fiber executing task_wait will block while the task is suspended, and the task's work will be executed inline on the fiber main context.

Return Value

Note

The return value should not be discarded.

Created with MrDocs