1 // 2 // dispatch.hpp 3 // ~~~~~~~~~~~~ 4 // 5 // Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) 6 // 7 // Distributed under the Boost Software License, Version 1.0. (See accompanying 8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9 // 10 11 #ifndef BOOST_ASIO_DISPATCH_HPP 12 #define BOOST_ASIO_DISPATCH_HPP 13 14 #if defined(_MSC_VER) && (_MSC_VER >= 1200) 15 # pragma once 16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) 17 18 #include <boost/asio/detail/config.hpp> 19 #include <boost/asio/async_result.hpp> 20 #include <boost/asio/detail/type_traits.hpp> 21 #include <boost/asio/execution_context.hpp> 22 #include <boost/asio/execution/executor.hpp> 23 #include <boost/asio/is_executor.hpp> 24 25 #include <boost/asio/detail/push_options.hpp> 26 27 namespace boost { 28 namespace asio { 29 30 /// Submits a completion token or function object for execution. 31 /** 32 * This function submits an object for execution using the object's associated 33 * executor. The function object may be called from the current thread prior to 34 * returning from <tt>dispatch()</tt>. Otherwise, it is queued for execution. 35 * 36 * This function has the following effects: 37 * 38 * @li Constructs a function object handler of type @c Handler, initialized 39 * with <tt>handler(forward<CompletionToken>(token))</tt>. 40 * 41 * @li Constructs an object @c result of type <tt>async_result<Handler></tt>, 42 * initializing the object as <tt>result(handler)</tt>. 43 * 44 * @li Obtains the handler's associated executor object @c ex by performing 45 * <tt>get_associated_executor(handler)</tt>. 46 * 47 * @li Obtains the handler's associated allocator object @c alloc by performing 48 * <tt>get_associated_allocator(handler)</tt>. 49 * 50 * @li Performs <tt>ex.dispatch(std::move(handler), alloc)</tt>. 51 * 52 * @li Returns <tt>result.get()</tt>. 53 */ 54 template <BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) CompletionToken> 55 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(CompletionToken, void()) dispatch( 56 BOOST_ASIO_MOVE_ARG(CompletionToken) token); 57 58 /// Submits a completion token or function object for execution. 59 /** 60 * This function submits an object for execution using the specified executor. 61 * The function object may be called from the current thread prior to returning 62 * from <tt>dispatch()</tt>. Otherwise, it is queued for execution. 63 * 64 * This function has the following effects: 65 * 66 * @li Constructs a function object handler of type @c Handler, initialized 67 * with <tt>handler(forward<CompletionToken>(token))</tt>. 68 * 69 * @li Constructs an object @c result of type <tt>async_result<Handler></tt>, 70 * initializing the object as <tt>result(handler)</tt>. 71 * 72 * @li Obtains the handler's associated executor object @c ex1 by performing 73 * <tt>get_associated_executor(handler)</tt>. 74 * 75 * @li Creates a work object @c w by performing <tt>make_work(ex1)</tt>. 76 * 77 * @li Obtains the handler's associated allocator object @c alloc by performing 78 * <tt>get_associated_allocator(handler)</tt>. 79 * 80 * @li Constructs a function object @c f with a function call operator that 81 * performs <tt>ex1.dispatch(std::move(handler), alloc)</tt> followed by 82 * <tt>w.reset()</tt>. 83 * 84 * @li Performs <tt>Executor(ex).dispatch(std::move(f), alloc)</tt>. 85 * 86 * @li Returns <tt>result.get()</tt>. 87 */ 88 template <typename Executor, 89 BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) CompletionToken 90 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 91 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(CompletionToken, void()) dispatch( 92 const Executor& ex, 93 BOOST_ASIO_MOVE_ARG(CompletionToken) token 94 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), 95 typename constraint< 96 execution::is_executor<Executor>::value || is_executor<Executor>::value 97 >::type = 0); 98 99 /// Submits a completion token or function object for execution. 100 /** 101 * @returns <tt>dispatch(ctx.get_executor(), 102 * forward<CompletionToken>(token))</tt>. 103 */ 104 template <typename ExecutionContext, 105 BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) CompletionToken 106 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 107 typename ExecutionContext::executor_type)> 108 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(CompletionToken, void()) dispatch( 109 ExecutionContext& ctx, 110 BOOST_ASIO_MOVE_ARG(CompletionToken) token 111 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 112 typename ExecutionContext::executor_type), 113 typename constraint<is_convertible< 114 ExecutionContext&, execution_context&>::value>::type = 0); 115 116 } // namespace asio 117 } // namespace boost 118 119 #include <boost/asio/detail/pop_options.hpp> 120 121 #include <boost/asio/impl/dispatch.hpp> 122 123 #endif // BOOST_ASIO_DISPATCH_HPP 124