Futures Library: Future types

Basic future types.

This module defines the basic_future template class, which can be used to define futures with a number of extensions.

Futures / Future types

Classes

Classes	Description
basic_future	A basic future type with custom features. (class)

Types

Member Types	Definition
future_status	Specifies state of a future. (enum)
future	A simple future type similar to std::future (using)
cfuture	A future type with lazy continuations. (using)
jcfuture	A future type with lazy continuations and stop tokens. (using)
dfuture	A deferred future type. (using)
jdfuture	A deferred stoppable future type. (using)
vfuture	A future that simply holds a ready value. (using)
shared_future	A simple std::shared_future. (using)
shared_cfuture	A shared future type with lazy continuations. (using)
shared_jcfuture	A shared future type with lazy continuations and stop tokens. (using)
shared_dfuture	A shared future type with deferred task. (using)
shared_jdfuture	A shared future type with deferred task and stop token. (using)
shared_vfuture	A shared future that simply holds a ready value. (using)

Types

enum future_status

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

enum class future_status;

Enumerator	Value	Description
ready		The operation state is ready.
timeout		The operation state did not become ready before specified timeout duration has passed.
deferred		The operation state contains a deferred function, so the result will be computed only when explicitly requested.

Specifies state of a future.

Description

Specifies state of a future as returned by wait_for and wait_until functions of basic_future.

using future

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

template <class T, class Executor = default_executor_type>
using future = 
    basic_future< T, future_options< executor_opt< Executor > > >;

A simple future type similar to std::future

Description

We should only use this future type for eager tasks that do not expect continuations.

using cfuture

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

template <class T, class Executor = default_executor_type>
using cfuture = 
    basic_future< T, future_options< executor_opt< Executor >, continuable_opt > >;

A future type with lazy continuations.

Description

Futures with lazy continuations contains a list of continuation tasks to be launched once the main task is complete.

This is what a futures::async returns by default when the first function parameter is not a futures::stop_token.

using jcfuture

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

template <class T, class Executor = default_executor_type>
using jcfuture = 
    basic_future< T, future_options< executor_opt< Executor >, continuable_opt, stoppable_opt > >;

A future type with lazy continuations and stop tokens.

Description

It's a quite common use case that we need a way to cancel futures and jcfuture provides us with an even better way to do that.

This is what futures::async returns when the first function parameter is a futures::stop_token

using dfuture

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

template <class T, class Executor = default_executor_type>
using dfuture = 
    basic_future< T, future_options< executor_opt< Executor >, always_deferred_opt > >;

A deferred future type.

Description

This is a future type whose main task will only be launched when we wait for its results from another execution context.

This is what the function schedule returns when the first task parameter is not a stop token.

The state of this future stores the function to be run.

This future type supports continuations without the continuation lists of continuable futures.

using jdfuture

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

template <class T, class Executor = default_executor_type>
using jdfuture = 
    basic_future< T, future_options< executor_opt< Executor >, always_deferred_opt > >;

A deferred stoppable future type.

Description

This is a future type whose main task will only be launched when we wait for its results from another execution context.

Once the task is launched, it can be requested to stop through its stop source.

This is what the function schedule returns when the first task parameter is a stop token.

using vfuture

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

template <class T>
using vfuture = basic_future< T, future_options<> >;

A future that simply holds a ready value.

Description

This is the future type we use for constant values. This is the future type we usually return from functions such as make_ready_future.

These futures have no support for associated executors, continuations, or deferred tasks.

Like deferred futures, the operation state is stored inline.

using shared_future

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

template <class T, class Executor = default_executor_type>
using shared_future = 
    basic_future< T, future_options< executor_opt< Executor >, shared_opt > >;

A simple std::shared_future.

Description

This is what a futures::future::share() returns

using shared_cfuture

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

template <class T, class Executor = default_executor_type>
using shared_cfuture = 
    basic_future< T, future_options< executor_opt< Executor >, continuable_opt, shared_opt > >;

A shared future type with lazy continuations.

Description

This is what a futures::cfuture::share() returns

using shared_jcfuture

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

template <class T, class Executor = default_executor_type>
using shared_jcfuture = 
    basic_future< T, future_options< executor_opt< Executor >, continuable_opt, stoppable_opt, shared_opt > >;

A shared future type with lazy continuations and stop tokens.

Description

This is what a futures::jcfuture::share() returns

using shared_dfuture

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

template <class T, class Executor = default_executor_type>
using shared_dfuture = 
    basic_future< T, future_options< executor_opt< Executor >, always_deferred_opt, shared_opt > >;

A shared future type with deferred task.

Description

This is what a futures::dfuture::share() returns

using shared_jdfuture

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

template <class T, class Executor = default_executor_type>
using shared_jdfuture = 
    basic_future< T, future_options< executor_opt< Executor >, stoppable_opt, always_deferred_opt, shared_opt > >;

A shared future type with deferred task and stop token.

Description

This is what a futures::jdfuture::share() returns

using shared_vfuture

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

template <class T>
using shared_vfuture = 
    basic_future< T, future_options< shared_opt > >;

A shared future that simply holds a ready value.

---

_{Updated on 2023-01-04}