Why is SafeTask.h useful?

Synopsis

Declared in <folly/coro/safe/SafeTask.h>

template<
    safe_alias ArgSafety,
    typename T = void>
class [[nodiscard]] safe_task final
    : public /* implementation-defined */::type

Description

now_task from NowTask.h should be your default. This immovable task should always be awaited in the full‐expression that created it, eliminating most classes of lifetime‐safety bugs.

If you need a MOVABLE task with compile‐time safety checks, read on.

Typically, you will not use safe_task directly. Instead, choose one of the type‐aliases below, following APIBestPractices.md guidance. Briefly:

value_task: Use if your coro only takes value‐semantic args.

member_task: Use for non‐static member functions. Can be awaited immediately (like now_task), or wrapped in an async_closure to support less‐structured concurrency ‐‐ including scheduling on a background scope belonging to the object. IMPORTANT: adding a member_task to a class requires it to have an explicit folly/lang/SafeAlias.h annotation.

closure_task: Use if your coro is called via async_closure. Outside of closures, this behaves like now_task.

co_cleanup_safe_task: Use for tasks that can be directly scheduled on a safe_async_scope.

auto_safe_task: Generic coros where you want the argument & return types to automatically choose between a now_task and a safe_task.

safe_task is a thin wrapper around folly::coro::Task that uses safe_alias_of to enforce some compile‐time guarantees:

  • The safe_task has safe_alias_of memory safety at least as high as the coro's arguments. In particular, no args are taken by reference.

  • Regardless of the task's declared safety, the coro's return must have safety maybe_value (explained in safe_task_ret_and_args).

  • The coroutine is NOT a stateful callable ‐‐ this prohibits lambda captures, since those are a very common cause of coro memory bugs.

Base Classes

Name

Description

/* implementation-defined */::type

Type Aliases

Name

Description

folly_private_safe_alias_t

Reports the safe‐alias level of this task to the SafeAlias machinery.

Member Functions

Name

Description

as_unsafe [deprecated]

Unwraps this task into a plain Task, dropping the safety guarantees.

Using Declarations

Name

Unnamed using

Protected Member Functions

Name

Description

withNewSafety

Re‐wraps this task as a safe_task with a different declared safety level.

Friends

Name

Description

folly::coro::to_now_task

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

folly::coro::safe_task

Why is SafeTask.h useful?

Non-Member Functions

Name

Description

to_now_task

Converts a safe_task into an equivalent now_task.

Return Value

Note

The return value should not be discarded.

Created with MrDocs