13 Asynchronous model [async]

13.22 Function dispatch [async.dispatch]

Note: The function dispatch satisfies the requirements for an asynchronous operation ([async.reqmts.async]), except for the requirement that the operation uses post if it completes immediately.  — end note ]

template<class CompletionToken> DEDUCED dispatch(CompletionToken&& token);

Completion signature: void().

Effects:

  • Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.

  • Performs ex.dispatch(std::move(completion.completion_handler), alloc), where ex is the result of get_associated_executor(completion.completion_handler), and alloc is the result of get_associated_allocator(completion.completion_handler).

Returns: completion.result.get().

template<class Executor, class CompletionToken> DEDUCED dispatch(const Executor& ex, CompletionToken&& token);

Completion signature: void().

Effects:

  • Constructs an object completion of type async_completion<CompletionToken, void()>, initialized with token.

  • Constructs a function object f containing as members:

    • a copy of the completion handler h, initialized with std::move(completion.completion_handler),

    • an executor_work_guard object w for the completion handler's associated executor, initialized with make_work_guard(h),

    and where the effect of f() is:

    • w.get_executor().dispatch(std::move(h), alloc), where alloc is the result of get_associated_allocator(h), followed by

    • w.reset().

  • Performs ex.dispatch(std::move(f), alloc), where alloc is the result of get_associated_allocator(completion.completion_handler) prior to the construction of f.

Returns: completion.result.get().

Remarks: This function shall not participate in overload resolution unless is_executor_v<Executor> is true.

template<class ExecutionContext, class CompletionToken> DEDUCED dispatch(ExecutionContext& ctx, CompletionToken&& token);

Completion signature: void().

Returns: net::dispatch(ctx.get_executor(), forward<CompletionToken>(token)).

Remarks: This function shall not participate in overload resolution unless is_convertible<ExecutionContext&, execution_context&>::value is true.