1 // 2 // defer.hpp 3 // ~~~~~~~~~ 4 // 5 // Copyright (c) 2003-2020 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_DEFER_HPP 12 #define BOOST_ASIO_DEFER_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 is queued for execution, and is never called 34 * from the current thread prior to returning from <tt>defer()</tt>. 35 * 36 * The use of @c defer(), rather than @ref post(), indicates the caller's 37 * preference that the executor defer the queueing of the function object. This 38 * may allow the executor to optimise queueing for cases when the function 39 * object represents a continuation of the current call context. 40 * 41 * This function has the following effects: 42 * 43 * @li Constructs a function object handler of type @c Handler, initialized 44 * with <tt>handler(forward<CompletionToken>(token))</tt>. 45 * 46 * @li Constructs an object @c result of type <tt>async_result<Handler></tt>, 47 * initializing the object as <tt>result(handler)</tt>. 48 * 49 * @li Obtains the handler's associated executor object @c ex by performing 50 * <tt>get_associated_executor(handler)</tt>. 51 * 52 * @li Obtains the handler's associated allocator object @c alloc by performing 53 * <tt>get_associated_allocator(handler)</tt>. 54 * 55 * @li Performs <tt>ex.defer(std::move(handler), alloc)</tt>. 56 * 57 * @li Returns <tt>result.get()</tt>. 58 */ 59 template <BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) CompletionToken> 60 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(CompletionToken, void()) defer( 61 BOOST_ASIO_MOVE_ARG(CompletionToken) token); 62 63 /// Submits a completion token or function object for execution. 64 /** 65 * This function submits an object for execution using the specified executor. 66 * The function object is queued for execution, and is never called from the 67 * current thread prior to returning from <tt>defer()</tt>. 68 * 69 * The use of @c defer(), rather than @ref post(), indicates the caller's 70 * preference that the executor defer the queueing of the function object. This 71 * may allow the executor to optimise queueing for cases when the function 72 * object represents a continuation of the current call context. 73 * 74 * This function has the following effects: 75 * 76 * @li Constructs a function object handler of type @c Handler, initialized 77 * with <tt>handler(forward<CompletionToken>(token))</tt>. 78 * 79 * @li Constructs an object @c result of type <tt>async_result<Handler></tt>, 80 * initializing the object as <tt>result(handler)</tt>. 81 * 82 * @li Obtains the handler's associated executor object @c ex1 by performing 83 * <tt>get_associated_executor(handler)</tt>. 84 * 85 * @li Creates a work object @c w by performing <tt>make_work(ex1)</tt>. 86 * 87 * @li Obtains the handler's associated allocator object @c alloc by performing 88 * <tt>get_associated_allocator(handler)</tt>. 89 * 90 * @li Constructs a function object @c f with a function call operator that 91 * performs <tt>ex1.dispatch(std::move(handler), alloc)</tt> followed by 92 * <tt>w.reset()</tt>. 93 * 94 * @li Performs <tt>Executor(ex).defer(std::move(f), alloc)</tt>. 95 * 96 * @li Returns <tt>result.get()</tt>. 97 */ 98 template <typename Executor, 99 BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) CompletionToken 100 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 101 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(CompletionToken, void()) defer( 102 const Executor& ex, 103 BOOST_ASIO_MOVE_ARG(CompletionToken) token 104 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), 105 typename enable_if< 106 execution::is_executor<Executor>::value || is_executor<Executor>::value 107 >::type* = 0); 108 109 /// Submits a completion token or function object for execution. 110 /** 111 * @returns <tt>defer(ctx.get_executor(), forward<CompletionToken>(token))</tt>. 112 */ 113 template <typename ExecutionContext, 114 BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) CompletionToken 115 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( 116 typename ExecutionContext::executor_type)> 117 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(CompletionToken, void()) defer( 118 ExecutionContext& ctx, 119 BOOST_ASIO_MOVE_ARG(CompletionToken) token 120 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( 121 typename ExecutionContext::executor_type), 122 typename enable_if<is_convertible< 123 ExecutionContext&, execution_context&>::value>::type* = 0); 124 125 } // namespace asio 126 } // namespace boost 127 128 #include <boost/asio/detail/pop_options.hpp> 129 130 #include <boost/asio/impl/defer.hpp> 131 132 #endif // BOOST_ASIO_DEFER_HPP 133