future

Detailed Description

Futures, packaged tasks, and coroutine integration.

The long-form overview (lifecycle, cancellation, continuations, coroutines) is in the file-level comment at the top of this header. This module groups the public API declared here: future, packaged_task, package, async, when_all, when_any, resume_on, and related helpers.

Classes
struct	stlab::void_to_monostate< T >
	Maps void to std::monostate for uniform future result storage; other types unchanged. More...
class	stlab::future_error
	Exception thrown when a future-related contract is violated (e.g. broken_promise, no_state). More...
class	stlab::packaged_task< Args >
	Invocable that completes a future when called with arguments of type Args...; created by package(). More...
class	stlab::future< class, class >
	One-shot asynchronous result: holds a value or exception produced by a promise or packaged_task. More...
class	stlab::future< T, enable_if_copyable< void_to_monostate_t< T > > >
	Consumer side of a one-shot result (copyable T). More...
class	stlab::future< T, enable_if_not_copyable< void_to_monostate_t< T > > >
	Consumer side of a one-shot result (non-copyable T). More...
struct	stlab::make_when_any< T >
	Helper to implement when_any for result type T. More...
struct	stlab::make_when_any< void >
	Helper to implement when_any for void results. More...

Typedefs
template<class T>
using	stlab::void_to_monostate_t
	Alias for void_to_monostate<T>::type.

Enumerations
enum class	stlab::future_error_codes : std::uint8_t { stlab::future_error_codes::broken_promise , stlab::future_error_codes::no_state }
	Error codes for future_error. More...

Functions
template<class F, class... Args>
auto	stlab::invoke_void_to_monostate_result (F &&f, Args &&... args)
	Invokes f with args and returns its result, or std::monostate{} if the result is void.
template<class T>
auto	stlab::optional_monostate_to_bool (std::optional< T > &&o)
	Returns o.has_value() when T is std::monostate, otherwise std::move(o).
template<class T>
auto	stlab::monostate_to_void (T &&a)
	Converts std::monostate to void (no return); forwards other types unchanged.
template<class T>
auto	stlab::monostate_to_empty_tuple (T &&a)
	Converts std::monostate to std::tuple{}; wraps other types in std::tuple for uniform application.
template<class F, class... Args>
auto	stlab::invoke_remove_monostate_arguments (F &&f, Args &&... args)
	Invokes f with args after removing std::monostate values (for void future results).
template<class Sig, class E, class F>
auto	stlab::package (E &&executor, F &&f) -> std::pair< detail::packaged_task_from_signature_t< Sig >, detail::reduced_result_t< Sig > >
	Creates a packaged task and its future for the callable f, run on executor.
template<class T, class E>
auto	stlab::future_with_broken_promise (E &&executor) -> detail::reduced_t< T >
	Returns a future of type T that is already ready with a broken_promise error (e.g. for canceled work).
template<class E, class F, class... Ts>
auto	stlab::when_all (const E &executor, F f, future< Ts >... args)
	Returns a future for f scheduled on executor with all input values.
template<class E, class F, class T, class... Ts>
auto	stlab::when_any (E &&executor, F &&f, future< T > &&arg, future< Ts > &&... args)
	Returns a future for f invoked with the first successful input's value and its std::size_t index. For void inputs, f receives only the index. If every input fails, propagates the last failure without invoking f. Selection occurs when inputs complete; value extraction and f run on executor. Destroying the submitted task without invoking it completes the result with future_error_codes::broken_promise.
template<class E, class F, class I>
auto	stlab::when_all (const E &executor, F f, std::pair< I, I > range)
	Returns a future for f scheduled on executor with the input range's values in input order.
template<class E, class F, class I>
auto	stlab::when_any (const E &executor, F &&f, std::pair< I, I > range)
	Returns a future for f invoked with the first successful input's value and its std::size_t index in [range.first, range.second). For void inputs, f receives only the index. If every input fails, propagates the last failure without invoking f. Selection occurs when inputs complete; value extraction and f run on executor. Destroying the submitted task without invoking it completes the result with future_error_codes::broken_promise.
template<class E, class F, class... Args>
auto	stlab::async (const E &executor, F &&f, Args &&... args) -> detail::reduced_t< detail::result_t< std::decay_t< F >, std::decay_t< Args >... > >
	Runs f with args on executor and returns a future for the result.

Variables
template<class T>
constexpr bool	stlab::is_monostate_v
	True if T is std::monostate.

Enumeration Type Documentation

future_error_codes

enum class stlab::future_error_codes : std::uint8_t

strong

Error codes for future_error.

Enumerator
broken_promise	Promise was destroyed without setting a value or exception.
no_state	Operation required a valid shared state.

Function Documentation

async()

template<class E, class F, class... Args>

auto stlab::async	(	const E &	executor,
		F &&	f,
		Args &&...	args ) -> detail::reduced_t< detail::result_t< std::decay_t< F >, std::decay_t< Args >... > >

Runs f with args on executor and returns a future for the result.

The packaged task is submitted by invoking executor with the task; the returned future completes when f returns or throws (exceptions become the future's error).

package()

template<class Sig, class E, class F>

auto stlab::package	(	E &&	executor,
		F &&	f ) -> std::pair< detail::packaged_task_from_signature_t< Sig >, detail::reduced_result_t< Sig > >

Creates a packaged task and its future for the callable f, run on executor.

Creates a packaged_task and its future for signature Sig, using executor to run f when the task is invoked.

Returns

A pair (packaged_task, future); invoke the task to run f and complete the future.

when_all() [1/2]

template<class E, class F, class... Ts>

auto stlab::when_all	(	const E &	executor,
		F	f,
		future< Ts >...	args )

Returns a future for f scheduled on executor with all input values.

The first input failure ends the join without invoking f. The join releases its interest in inputs no longer needed. Destroying the submitted task without invoking it completes the result with future_error_codes::broken_promise. Value extraction also runs on executor. A variadic empty pack is not supported; use the iterator-range overload for the empty case.

• Complexity: linear time and storage in the number of inputs, excluding user operations.

Examples

when_all(executor, [](int a, int b) { return a + b; }, first, second) joins two integer futures.

when_all() [2/2]

template<class E, class F, class I>

auto stlab::when_all	(	const E &	executor,
		F	f,
		std::pair< I, I >	range )

Returns a future for f scheduled on executor with the input range's values in input order.

If range is empty, the continuation is still scheduled on executor with an empty result collection (no futures to wait on). For a non-empty range, elements that are move-only are moved out of the iterators while attaching continuations. The first input failure ends the join without invoking f. Destroying the submitted task without invoking it completes the result with future_error_codes::broken_promise. Value extraction also runs on executor.

• Complexity: linear time and storage in the number of inputs, excluding user operations.

Examples

when_all(executor, [](std::vector<int> values) { return values; }, std::pair{first, last}) collects an iterator range of integer futures.

when_any() [1/2]

template<class E, class F, class I>

auto stlab::when_any	(	const E &	executor,
		F &&	f,
		std::pair< I, I >	range )

Returns a future for f invoked with the first successful input's value and its std::size_t index in [range.first, range.second). For void inputs, f receives only the index. If every input fails, propagates the last failure without invoking f. Selection occurs when inputs complete; value extraction and f run on executor. Destroying the submitted task without invoking it completes the result with future_error_codes::broken_promise.

If range is empty, returns an already-failed future via future_with_broken_promise (there is no candidate to complete first).

• Complexity: linear time and storage in the number of inputs, excluding user operations.

Examples

when_any(executor, [](int value, std::size_t) { return value; }, std::pair{first, last}) selects a successful integer future from an iterator range.

when_any() [2/2]

template<class E, class F, class T, class... Ts>

auto stlab::when_any	(	E &&	executor,
		F &&	f,
		future< T > &&	arg,
		future< Ts > &&...	args )

Returns a future for f invoked with the first successful input's value and its std::size_t index. For void inputs, f receives only the index. If every input fails, propagates the last failure without invoking f. Selection occurs when inputs complete; value extraction and f run on executor. Destroying the submitted task without invoking it completes the result with future_error_codes::broken_promise.

Details

For non-void inputs, every value type must be convertible to the first parameter of f. An empty variadic pack is not supported—use the iterator-range overload with an empty range if needed.

• Complexity: linear time and storage in the number of inputs, excluding user operations.

Examples

when_any(executor, [](int value, std::size_t) { return value; }, std::move(a), std::move(b)) returns the first successful integer result.