future

Detailed Description

Futures, packaged tasks, channels, 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, channel aliases, 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). Use get_ready() or get_try(); then/recover only on rvalue. 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 that completes when all input futures are ready; f receives their 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 that completes when any of the given futures is ready; f receives the value and the index of the future that completed first (as a second argument of type std::size_t).
template<class E, class F, class I>
auto	stlab::when_all (const E &executor, F f, std::pair< I, I > range)
	Returns a future that completes when all futures in [range.first, range.second) are ready; f receives their values.
template<class E, class F, class I>
auto	stlab::when_any (const E &executor, F &&f, std::pair< I, I > range)
	Returns a future that completes when any future in [range.first, range.second) is ready; f receives the result and the index of the future that completed first (as a second argument of type std::size_t).
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 that completes when all input futures are ready; f receives their values.

If any input completes with an exception, that error ends the combined operation (remaining work is canceled per the implementation). A variadic empty pack is not supported; use the iterator-range overload if you need the empty case.

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 that completes when all futures in [range.first, range.second) are ready; f receives their values.

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.

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 that completes when any future in [range.first, range.second) is ready; f receives the result and the index of the future that completed first (as a second argument of type std::size_t).

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

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 that completes when any of the given futures is ready; f receives the value and the index of the future that completed first (as a second argument of type std::size_t).

Details

Every input future’s 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.