]>
Commit | Line | Data |
---|---|---|
b32b8144 FG |
1 | // |
2 | // post.hpp | |
3 | // ~~~~~~~~ | |
4 | // | |
1e59de90 | 5 | // Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
b32b8144 FG |
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_POST_HPP | |
12 | #define BOOST_ASIO_POST_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> | |
20effc67 | 22 | #include <boost/asio/execution/executor.hpp> |
b32b8144 FG |
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>post()</tt>. | |
35 | * | |
92f5a8d4 TL |
36 | * The use of @c post(), rather than @ref defer(), indicates the caller's |
37 | * preference that the function object be eagerly queued for execution. | |
38 | * | |
1e59de90 TL |
39 | * @param token The @ref completion_token that will be used to produce a |
40 | * completion handler. The function signature of the completion handler must be: | |
41 | * @code void handler(); @endcode | |
b32b8144 | 42 | * |
1e59de90 TL |
43 | * @returns This function returns <tt>async_initiate<NullaryToken, |
44 | * void()>(Init{}, token)</tt>, where @c Init is a function object type defined | |
45 | * as: | |
b32b8144 | 46 | * |
1e59de90 TL |
47 | * @code class Init |
48 | * { | |
49 | * public: | |
50 | * template <typename CompletionHandler> | |
51 | * void operator()(CompletionHandler&& completion_handler) const; | |
52 | * }; @endcode | |
b32b8144 | 53 | * |
1e59de90 | 54 | * The function call operator of @c Init: |
b32b8144 | 55 | * |
1e59de90 TL |
56 | * @li Obtains the handler's associated executor object @c ex of type @c Ex by |
57 | * performing @code auto ex = get_associated_executor(handler); @endcode | |
b32b8144 | 58 | * |
1e59de90 TL |
59 | * @li Obtains the handler's associated allocator object @c alloc by performing |
60 | * @code auto alloc = get_associated_allocator(handler); @endcode | |
61 | * | |
62 | * @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs | |
63 | * @code execution::execute( | |
64 | * prefer( | |
65 | * require(ex, execution::blocking.never), | |
66 | * execution::relationship.fork, | |
67 | * execution::allocator(alloc)), | |
68 | * std::forward<CompletionHandler>(completion_handler)); @endcode | |
69 | * | |
70 | * @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs | |
71 | * @code ex.post( | |
72 | * std::forward<CompletionHandler>(completion_handler), | |
73 | * alloc); @endcode | |
74 | * | |
75 | * @par Completion Signature | |
76 | * @code void() @endcode | |
b32b8144 | 77 | */ |
1e59de90 TL |
78 | template <BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken> |
79 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(NullaryToken, void()) post( | |
80 | BOOST_ASIO_MOVE_ARG(NullaryToken) token); | |
b32b8144 FG |
81 | |
82 | /// Submits a completion token or function object for execution. | |
83 | /** | |
84 | * This function submits an object for execution using the specified executor. | |
85 | * The function object is queued for execution, and is never called from the | |
86 | * current thread prior to returning from <tt>post()</tt>. | |
87 | * | |
92f5a8d4 TL |
88 | * The use of @c post(), rather than @ref defer(), indicates the caller's |
89 | * preference that the function object be eagerly queued for execution. | |
90 | * | |
1e59de90 | 91 | * @param ex The target executor. |
b32b8144 | 92 | * |
1e59de90 TL |
93 | * @param token The @ref completion_token that will be used to produce a |
94 | * completion handler. The function signature of the completion handler must be: | |
95 | * @code void handler(); @endcode | |
b32b8144 | 96 | * |
1e59de90 TL |
97 | * @returns This function returns <tt>async_initiate<NullaryToken, |
98 | * void()>(Init{ex}, token)</tt>, where @c Init is a function object type | |
99 | * defined as: | |
b32b8144 | 100 | * |
1e59de90 TL |
101 | * @code class Init |
102 | * { | |
103 | * public: | |
104 | * using executor_type = Executor; | |
105 | * explicit Init(const Executor& ex) : ex_(ex) {} | |
106 | * executor_type get_executor() const noexcept { return ex_; } | |
107 | * template <typename CompletionHandler> | |
108 | * void operator()(CompletionHandler&& completion_handler) const; | |
109 | * private: | |
110 | * Executor ex_; // exposition only | |
111 | * }; @endcode | |
b32b8144 | 112 | * |
1e59de90 | 113 | * The function call operator of @c Init: |
b32b8144 | 114 | * |
1e59de90 TL |
115 | * @li Obtains the handler's associated executor object @c ex1 of type @c Ex1 by |
116 | * performing @code auto ex1 = get_associated_executor(handler, ex); @endcode | |
b32b8144 | 117 | * |
1e59de90 TL |
118 | * @li Obtains the handler's associated allocator object @c alloc by performing |
119 | * @code auto alloc = get_associated_allocator(handler); @endcode | |
120 | * | |
121 | * @li If <tt>execution::is_executor<Ex1>::value</tt> is true, constructs a | |
122 | * function object @c f with a member @c executor_ that is initialised with | |
123 | * <tt>prefer(ex1, execution::outstanding_work.tracked)</tt>, a member @c | |
124 | * handler_ that is a decay-copy of @c completion_handler, and a function call | |
125 | * operator that performs: | |
126 | * @code auto a = get_associated_allocator(handler_); | |
127 | * execution::execute( | |
128 | * prefer(executor_, | |
129 | * execution::blocking.possibly, | |
130 | * execution::allocator(a)), | |
131 | * std::move(handler_)); @endcode | |
132 | * | |
133 | * @li If <tt>execution::is_executor<Ex1>::value</tt> is false, constructs a | |
134 | * function object @c f with a member @c work_ that is initialised with | |
135 | * <tt>make_work_guard(ex1)</tt>, a member @c handler_ that is a decay-copy of | |
136 | * @c completion_handler, and a function call operator that performs: | |
137 | * @code auto a = get_associated_allocator(handler_); | |
138 | * work_.get_executor().dispatch(std::move(handler_), a); | |
139 | * work_.reset(); @endcode | |
140 | * | |
141 | * @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs | |
142 | * @code execution::execute( | |
143 | * prefer( | |
144 | * require(ex, execution::blocking.never), | |
145 | * execution::relationship.fork, | |
146 | * execution::allocator(alloc)), | |
147 | * std::move(f)); @endcode | |
148 | * | |
149 | * @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs | |
150 | * @code ex.post(std::move(f), alloc); @endcode | |
151 | * | |
152 | * @par Completion Signature | |
153 | * @code void() @endcode | |
b32b8144 | 154 | */ |
92f5a8d4 | 155 | template <typename Executor, |
1e59de90 | 156 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken |
92f5a8d4 | 157 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> |
1e59de90 | 158 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(NullaryToken, void()) post( |
92f5a8d4 | 159 | const Executor& ex, |
1e59de90 | 160 | BOOST_ASIO_MOVE_ARG(NullaryToken) token |
92f5a8d4 | 161 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), |
1e59de90 | 162 | typename constraint< |
20effc67 | 163 | execution::is_executor<Executor>::value || is_executor<Executor>::value |
1e59de90 | 164 | >::type = 0); |
b32b8144 FG |
165 | |
166 | /// Submits a completion token or function object for execution. | |
167 | /** | |
1e59de90 TL |
168 | * @param ctx An execution context, from which the target executor is obtained. |
169 | * | |
170 | * @param token The @ref completion_token that will be used to produce a | |
171 | * completion handler. The function signature of the completion handler must be: | |
172 | * @code void handler(); @endcode | |
173 | * | |
174 | * @returns <tt>post(ctx.get_executor(), forward<NullaryToken>(token))</tt>. | |
175 | * | |
176 | * @par Completion Signature | |
177 | * @code void() @endcode | |
b32b8144 | 178 | */ |
92f5a8d4 | 179 | template <typename ExecutionContext, |
1e59de90 | 180 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken |
92f5a8d4 TL |
181 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE( |
182 | typename ExecutionContext::executor_type)> | |
1e59de90 | 183 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(NullaryToken, void()) post( |
92f5a8d4 | 184 | ExecutionContext& ctx, |
1e59de90 | 185 | BOOST_ASIO_MOVE_ARG(NullaryToken) token |
92f5a8d4 TL |
186 | BOOST_ASIO_DEFAULT_COMPLETION_TOKEN( |
187 | typename ExecutionContext::executor_type), | |
1e59de90 TL |
188 | typename constraint<is_convertible< |
189 | ExecutionContext&, execution_context&>::value>::type = 0); | |
b32b8144 FG |
190 | |
191 | } // namespace asio | |
192 | } // namespace boost | |
193 | ||
194 | #include <boost/asio/detail/pop_options.hpp> | |
195 | ||
196 | #include <boost/asio/impl/post.hpp> | |
197 | ||
198 | #endif // BOOST_ASIO_POST_HPP |