...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Submits a completion token or function object for execution.
template< typename Executor, typename NullaryToken = default_completion_token_t<Executor>> auto post( const Executor & ex, NullaryToken && token = default_completion_token_t< Executor >(), constraint_t<(execution::is_executor< Executor >::value &&can_require< Executor, execution::blocking_t::never_t >::value)||is_executor< Executor >::value > = 0);
This function submits an object for execution using the specified executor.
The function object is queued for execution, and is never called from the
current thread prior to returning from post()
.
The use of post()
,
rather than defer
,
indicates the caller's preference that the function object be eagerly queued
for execution.
The target executor.
The completion token that will be used to produce a completion handler. The function signature of the completion handler must be:
void handler();
This function returns async_initiate<NullaryToken, void()>(Init{ex}, token)
,
where Init
is a function
object type defined as:
class Init { public: using executor_type = Executor; explicit Init(const Executor& ex) : ex_(ex) {} executor_type get_executor() const noexcept { return ex_; } template <typename CompletionHandler> void operator()(CompletionHandler&& completion_handler) const; private: Executor ex_; // exposition only };
The function call operator of Init:
Obtains the handler's associated executor object ex1
of type Ex1
by performing
auto ex1 = get_associated_executor(handler, ex);
Obtains the handler's associated allocator object alloc
by performing
auto alloc = get_associated_allocator(handler);
If execution::is_executor<Ex1>::value
is true, constructs a function
object f
with a member
executor_
that is initialised
with prefer(ex1, execution::outstanding_work.tracked)
,
a member handler_
that
is a decay-copy of completion_handler
,
and a function call operator that performs:
auto a = get_associated_allocator(handler_); prefer(executor_, execution::allocator(a)).execute(std::move(handler_));
If execution::is_executor<Ex1>::value
is false, constructs a function
object f
with a member
work_
that is initialised
with make_work_guard(ex1)
, a member handler_
that is a decay-copy of completion_handler
,
and a function call operator that performs:
auto a = get_associated_allocator(handler_); work_.get_executor().dispatch(std::move(handler_), a); work_.reset();
If execution::is_executor<Ex>::value
is true, performs
prefer( require(ex, execution::blocking.never), execution::relationship.fork, execution::allocator(alloc) ).execute(std::move(f));
If execution::is_executor<Ex>::value
is false, performs
ex.post(std::move(f), alloc);
void()