folly::coro::Task

Represents an allocated, but not‐started coroutine, which is not yet been bound to an executor.

Synopsis

Declared in <folly/coro/Task.h>

template<typename T = void>
class [[nodiscard]] Task;

Description

You can only co_await a Task from within another Task, in which case it is implicitly bound to the same executor as the parent Task.

Alternatively, you can explicitly provide an executor by calling co_withExecutor(executor, task()), which will return a not‐yet‐started TaskWithExecutor that can be `co_await`ed anywhere and that will automatically schedule the coroutine to start executing on the bound executor when it is `co_await`ed.

Within the body of a Task's coroutine, executor binding to the parent executor is maintained by implicitly transforming all 'co_await expr' expressions into `co_await co_viaIfAsync(parentExecutor, expr)' to ensure that the coroutine always resumes on the parent's executor.

The Task coroutine is RequestContext‐aware and will capture the current RequestContext at the time the coroutine function is either awaited or explicitly started and will save/restore the current RequestContext whenever the coroutine suspends and resumes at a co_await expression.

More documentation on how to use coroutines is available at https://github.com/facebook/folly/blob/main/folly/coro/README.md

refcode folly/docs/examples/folly/coro/Task.cpp

Type Aliases

Name

Description

PrivateAwaiterTypeForTests

Awaiter type exposed for use by tests.

StorageType

The storage type used to hold the task's result.

folly_private_safe_alias_t

Marks Task as unsafe for safe‐alias analysis.

promise_type

The coroutine promise type backing this task.

Member Functions

Name

Description

Task [constructor]

Constructors

~Task [destructor]

Destructor

operator=

Move‐assigns from another task.

scheduleOn [deprecated]

Legacy way to bind this task to an executor.

semi

Converts a Task into a SemiFuture object.

swap

Swaps the coroutine handles of two tasks.

Friends

Name

Description

folly::coro::TaskWithExecutor

Represents an allocated but not yet started coroutine that has already been bound to an executor.

folly::coro::tag_invoke

Invokes a callable and wraps its awaited result in a Task.

folly::coro::co_withCancellation

Attaches a cancellation token to the task.

folly::coro::co_viaIfAsync

Adapts the task to run on the given executor when awaited.

folly::coro::co_withExecutor

Specify the executor that this task should execute on: co_withExecutor(executor, std::move(task))

Non-Member Functions

Name

Description

accumulate

Accumulate the values from an input stream using a binary operation.

accumulate

Accumulate the values from an input stream into a single value, similar to std::accumulate.

co_transition_lock

Async version of the folly::transition_lock TODO: add more transition policies beyond just from upgrade to exclusive

collectAllRange

Concurrently await a range of value‐less awaitables.

collectAllRange

Concurrently await a range of awaitables and collect their results.

collectAllTryRange

Concurrently await a range of awaitables and collect a vector of Try results.

collectAllTryWindowed

Await a range of awaitables with bounded concurrency, collecting Try results.

collectAllWindowed

Await a range of awaitables with bounded concurrency, collecting results.

collectAllWindowed

Await a range of value‐less awaitables with bounded concurrency.

collectAny

Concurrently await awaitables and complete with the first result and index.

collectAnyNoDiscard

Concurrently await awaitables and return every result once one finishes.

collectAnyNoDiscardRange

Await a range of awaitables and return every result once one finishes.

collectAnyRange

Concurrently await a range of awaitables and return the first result and index.

collectAnyWithoutException

Concurrently await awaitables, returning the first success or last error.

collectAnyWithoutExceptionRange

Await a range of awaitables, returning the first success or last error.

detachOnCancel

detachOnCancel is used to handle operations that are hard to be cancelled. A typical use case is: The caller starts a task with timeout (in this case, 1 sec timeout). The task itself launches a long running job and the job doesn't handle cancellation (sleep_for in this example). The caller has timeout and the cancellation is propagated to the task. The detachOnCancel detects the cancellation and return immediately. However, the background task still runs until the thread join.

makeErrorTask

Make a Task that will trivially yield an Exception.

makeResultTask

Make a Task out of a Try.

makeTask

Make a Task that trivially returns with no return value.

makeTask

Same as makeTask(). See Unit

makeTask

Make a task that trivially returns a value.

retryWhen

Execute a given asynchronous operation returned by func(), retrying it on failure, if desired, after awaiting retryDelay(error).

sleep

Return a task that, when awaited, will sleep for the specified duration.

sleepReturnEarlyOnCancel

Return a task that, when awaited, will sleep for the specified duration.

timed_wait

Awaits awaitable, giving up after duration elapses.

toTask

Wrap a SemiFuture<Unit> in a Task without starting it.

toTask

Wrap a SemiAwaitable in a Task without starting it.

toTask

Wrap a referenced SemiAwaitable in a Task without starting it.

toTask

Wrap a Future<Unit> in a Task without starting it.

toTaskInterruptOnCancel

Converts a Future to a Task that cancels the future on cancellation.

toTaskInterruptOnCancel

Converts a SemiFuture to a Task that cancels the future on cancellation.

to_now_task

Converts a Task into an equivalent now_task.

to_now_task

Converts a Task into a now_task; friended so it can construct one.

::folly::fibers::async::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.

::folly::fibers::async::taskWait

Block on a void task's execution from an Async annotated function.

Return Value

Note	The return value should not be discarded.

Created with MrDocs