将一个函数提交到指定的目标执行器上运行,并将结果传递给完成处理程序。
template< typename Function, typename Executor, typename CompletionToken = default_completion_token_t<Executor>> auto dispatch( Function && function, const Executor & ex, CompletionToken && token = default_completion_token_t< Executor >(), constraint_t< !is_void< result_of_t< decay_t< Function >()> >::value > = 0, constraint_t<(execution::is_executor< Executor >::value &&can_require< Executor, execution::blocking_t::never_t >::value)||is_executor< Executor >::value > = 0);
此函数使用指定的执行器提交一个函数对象以供执行。该函数对象可能在返回 dispatch() 之前从当前线程调用。否则,它将被排队等待执行。提交的函数完成执行后,会将完成处理程序连同函数的返回结果一起分派到其关联的执行器上运行。
要在目标执行器上执行的无参函数。
目标执行器。
将用于生成完成处理程序的 完成令牌。完成处理程序的函数签名必须是
void handler(decay_t<result_of_t<decay_t<Function>()>>);
此函数返回 async_initiate<CompletionToken, void()>(Init{ex}, token),其中 Init 是一个函数对象类型,定义为
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, Function&& function) const; private: Executor ex_; // exposition only };
Init 的函数调用运算符:
通过执行以下操作获取处理程序的关联执行器对象 ex1,类型为 Ex1:
auto ex1 = get_associated_executor(completion_handler, ex);
通过执行以下操作获取处理程序的关联分配器对象 alloc:
auto alloc = get_associated_allocator(completion_handler);
如果 execution::is_executor<Ex1>::value 为 true,则构造一个函数对象包装器 f,其中包含一个成员 executor_,该成员使用 prefer(ex1, execution::outstanding_work.tracked) 进行初始化;一个成员 function_,它是 function 的 decay-copy;一个成员 handler_,它是 completion_handler 的 decay-copy;以及一个执行以下操作的函数调用运算符:
auto result = std::move(function_)(); auto a = get_associated_allocator(handler_); prefer(executor_, execution::allocator(a)).execute( std::bind(std::move(handler_), std::move(result)));
如果 execution::is_executor<Ex1>::value 为 false,则构造一个函数对象包装器 f,其中包含一个成员 work_,该成员使用 make_work_guard(ex1) 进行初始化;一个成员 function_,它是 function 的 decay-copy;一个成员 handler_,它是 completion_handler 的 decay-copy;以及一个执行以下操作的函数调用运算符:
auto result = std::move(function_)(); auto a = get_associated_allocator(handler_); work_.get_executor().dispatch( std::bind(std::move(handler_), std::move(result)), a); work_.reset();
如果 execution::is_executor<Executor>::value 为 true,则执行:
prefer( require(ex, execution::blocking.never), execution::relationship.fork, execution::allocator(alloc) ).execute(std::move(f));
如果 execution::is_executor<Executor>::value 为 false,则执行:
ex.dispatch(std::move(f), alloc);
如果函数对象抛出异常,该异常将被允许传播到目标执行器。在这种情况下,行为取决于执行器。例如,io_context 将允许异常传播到运行 io_context 的调用者,而 thread_pool 将调用 std::terminate。
void(decay_t<result_of_t<decay_t<Function>()>>)