Executors Library

Classes

Classes	Description
inline_executor	An executor that runs anything inline. ^(class)
new_thread_executor	An executor that runs anything in a new thread, like std::async does. ^(class)
thread_pool	A thread pool with the specified number of threads. ^(class)

Types

Member Types	Definition
default_execution_context_type	The default execution context for async operations. ^(using)
default_executor_type	Default executor type. ^(using)
is_execution_context_for	Determine if type is an execution context for the specified type of task. ^(using)
is_execution_context	Determines if a type is an execution context for invocable types. ^(using)
is_executor_for	Determine if type is an executor for the specified type of task. ^(using)
is_executor	Determines if a type is an executor for invocable types. ^(using)

Functions

Member Functions	Description
default_execution_context	Create an instance of the default execution context. ^(function)
make_default_executor	Create an Asio thread pool executor for the default thread pool. ^(function)
hardware_concurrency	A version of hardware_concurrency that always returns at least 1. ^(function)
make_inline_executor	Make an inline executor object. ^(function)
make_new_thread_executor	Make an new thread executor object. ^(function)

Attributes

Member Attributes	Description
is_execution_context_for_v	Determine if type is an execution context for the specified type of task. ^{(public variable template)}
is_execution_context_v	Determines if a type is an execution context for invocable types. ^{(public variable template)}
is_executor_for_v	Determine if type is an executor for the specified type of task. ^{(public variable template)}
is_executor_v	Determines if a type is an executor for invocable types. ^{(public variable template)}
execution_context_for	Determines if a type is an execution context for the a task type. ^{(public concept template)}
execution_context	The invocable archetype task is a regular functor. ^{(public concept template)}
executor_for	Determines if a type is an executor for the specified type of task. ^{(public concept template)}
executor	The invocable archetype task is a regular functor. ^{(public concept template)}

Types

using default_execution_context_type

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

using default_execution_context_type = /* see below */;

The default execution context for async operations.

Description

Unless an executor is explicitly provided, this is the executor we use for async operations.

This is the ASIO thread pool execution context with a default number of threads. However, the default execution context (and its type) might change in other versions of this library if something more general comes along. As the standard for executors gets adopted, libraries are likely to provide better implementations.

Also note that executors might not allow work-stealing. This needs to be taken into account when implementing algorithms with recursive tasks. One common options is to use try_async for recursive tasks.

Also note that, in the executors notation, the pool is an execution context but not an executor:

Execution context: a place where we can execute functions
A thread pool is an execution context, not an executor

An execution context is:

Usually long lived
Non-copyable
May contain additional state, such as timers, and threads

using default_executor_type

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

using default_executor_type = 
    default_execution_context_type::executor_type;

Default executor type.

using is_execution_context_for

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

template <class E, class F>
using is_execution_context_for = 
    std::bool_constant< execution_context_for< E, F > >;

Determine if type is an execution context for the specified type of task.

using is_execution_context

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

template <class E>
using is_execution_context = 
    std::bool_constant< execution_context< E > >;

Determines if a type is an execution context for invocable types.

using is_executor_for

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

template <class E, class F>
using is_executor_for = std::bool_constant< executor_for< E, F > >;

Determine if type is an executor for the specified type of task.

using is_executor

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

template <class E>
using is_executor = std::bool_constant< executor< E > >;

Determines if a type is an executor for invocable types.

Functions

function default_execution_context

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

default_execution_context_type &
default_execution_context();

Create an instance of the default execution context.

Return value

Reference to the default execution context for async

Exception Safety

Basic exception guarantee.

function make_default_executor

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

default_execution_context_type::executor_type
make_default_executor();

Create an Asio thread pool executor for the default thread pool.

Return value

Executor handle to the default execution context

Description

In the executors notation:

Executor: set of rules governing where, when and how to run a function object
- A thread pool is an execution context for which we can create executors pointing to the pool.
- The executor rule for the default thread pool executor is to run function objects in the pool and nowhere else.

An executor is:

Lightweight and copyable (just references and pointers to the execution context).
May be long or short lived.
May be customized on a fine-grained basis, such as exception behavior, and order

There might be many executor types associated with with the same execution context.

Exception Safety

Basic exception guarantee.

function hardware_concurrency

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

unsigned int
hardware_concurrency() noexcept;

A version of hardware_concurrency that always returns at least 1.

Return value

Number of concurrent threads supported. If the value is not well-defined or not computable, returns 1.

Description

This function is a safer version of hardware_concurrency that always returns at least 1 to represent the current context when the value is not computable.

It never returns 0, 1 is returned instead.
It is guaranteed to remain constant for the duration of the program.

It also improves on hardware_concurrency to provide a default value of 1 when the function is being executed at compile time. This allows partitioners and algorithms to be constexpr.

Exception Safety

Throws nothing.

See Also

std::hardware_concurrency

function make_inline_executor

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

constexpr inline_executor
make_inline_executor();

Make an inline executor object.

Exception Safety

Basic exception guarantee.

function make_new_thread_executor

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

constexpr new_thread_executor
make_new_thread_executor();

Make an new thread executor object.

Exception Safety

Basic exception guarantee.

Attributes

variable is_execution_context_for_v

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

constexpr bool is_execution_context_for_v = execution_context_for<E, F>;

Determine if type is an execution context for the specified type of task.

variable is_execution_context_v

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

constexpr bool is_execution_context_v = execution_context<E>;

Determines if a type is an execution context for invocable types.

variable is_executor_for_v

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

constexpr bool is_executor_for_v = executor_for<E, F>;

Determine if type is an executor for the specified type of task.

variable is_executor_v

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

constexpr bool is_executor_v = executor<E>;

Determines if a type is an executor for invocable types.

concept execution_context_for

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

template<class C, class F>
concept execution_context_for = 
        requires(C ctx, F f) {
            { ctx.get_executor() } -> executor_for<F>;
        };

Determines if a type is an execution context for the a task type.

concept execution_context

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

template<class C>
concept execution_context = execution_context_for<C, __invocable_archetype__ >;

The invocable archetype task is a regular functor.

Description

This means this trait should work for any execution context that supports non-heterogeneous tasks.

concept executor_for

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

template<class E, class F>
concept executor_for = requires(E e, F f) { e.execute(f); };

Determines if a type is an executor for the specified type of task.

concept executor

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

template<class E>
concept executor = executor_for<E, __invocable_archetype__ >;

The invocable archetype task is a regular functor.

Description

Determines if a type is an executor for invocable types.

Determines if a type is an execution context for invocable types.

This means this trait should work for any executor that supports non-heterogeneous tasks.

_{Updated on 2023-01-04}