Futures Library: Launch

Function to launch and schedule future tasks.

This module contains functions we can use to launch and schedule tasks. Tasks can be scheduled lazily instead of eagerly to avoid a race between the task and its dependencies.

When tasks are scheduled eagerly, the function async provides an alternatives to launch tasks on specific executors instead of creating a new thread for each asynchronous task.

Futures / Launch

Functions

Member Functions	Description
async	Launch an asynchronous task with the specified executor. (function template)
schedule	Schedule an asynchronous task with the specified executor. (function template)

Functions

function async

^{Defined in header <futures/launch.hpp>}

(1)

template <executor Executor, class Function, class... Args>
requires /* see requirements below */
/* see return type below */
async(Executor const & ex, Function && f, Args &&... args);

(2)

template <class Function, class... Args>
requires /* see requirements below */
/* see return type below */
async(Function && f, Args &&... args);

1. Launch an asynchronous task with the specified executor.
2. Launch an asynchronous task with the default executor.

Template Parameters

• Args - Arguments for the Function
• Executor - Executor from an execution context
• Function - A callable object

Parameters

• args - Function arguments
• ex - Executor
• f - Function to execute

Return value

• (1) A future object with the function results
• (2) An eager future object whose shared state refers to the task result. The type of this future object depends on the task. If the task expects a stop_token, the future will return a continuable, stoppable, eager future. Otherwise, the function will return a continuable eager future.

Description

This version of the async function will always use the specified executor instead of creating a new thread.

If no executor is provided, then the function is run in a default executor created from the default thread pool. The default executor also ensures the function will not launch one thread per task.

The task might accept a stop token as its first parameter, in which case the function returns a continuable and stoppable future type. Otherwise, this function returns a continuable future type.

Example

auto f = async(ex, []() { return 2; });
std::cout << f.get() << std::endl; // 2

Exception Safety

Basic exception guarantee.

See Also

• basic_future

function schedule

^{Defined in header <futures/launch.hpp>}

(1)

template <executor Executor, class Function, class... Args>
requires /* see requirements below */
/* see return type below */
schedule(Executor const & ex, Function && f, Args &&... args);

(2)

template <class Function, class... Args>
requires /* see requirements below */
/* see return type below */
schedule(Function && f, Args &&... args);

1. Schedule an asynchronous task with the specified executor.
2. Schedule an asynchronous task with the default executor.

Template Parameters

• Args - Arguments for the Function
• Executor - Executor from an execution context
• Function - A callable object

Parameters

• args - Function arguments
• ex - Executor
• f - Function to execute

Return value

• (1) A deferred future object whose shared state refers to the task result. The type of this future object depends on the task. If the task expects a stop_token, the future will return a stoppable deferred future. Otherwise, the function will return a deferred future.
• (2) A future object with the function results

Description

This function schedules a deferred future. The task will only be launched in the executor when some other execution context waits for the value associated to this future.

Exception Safety

Basic exception guarantee.

See Also

• basic_future

---

_{Updated on 2023-01-04}