]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // |
b32b8144 FG |
2 | // io_context_strand.hpp |
3 | // ~~~~~~~~~~~~~~~~~~~~~ | |
7c673cae | 4 | // |
92f5a8d4 | 5 | // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
7c673cae 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 | ||
b32b8144 FG |
11 | #ifndef BOOST_ASIO_IO_CONTEXT_STRAND_HPP |
12 | #define BOOST_ASIO_IO_CONTEXT_STRAND_HPP | |
7c673cae FG |
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> | |
b32b8144 FG |
19 | |
20 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) | |
21 | ||
7c673cae FG |
22 | #include <boost/asio/async_result.hpp> |
23 | #include <boost/asio/detail/handler_type_requirements.hpp> | |
24 | #include <boost/asio/detail/strand_service.hpp> | |
25 | #include <boost/asio/detail/wrapped_handler.hpp> | |
b32b8144 | 26 | #include <boost/asio/io_context.hpp> |
7c673cae FG |
27 | |
28 | #include <boost/asio/detail/push_options.hpp> | |
29 | ||
30 | namespace boost { | |
31 | namespace asio { | |
32 | ||
33 | /// Provides serialised handler execution. | |
34 | /** | |
b32b8144 | 35 | * The io_context::strand class provides the ability to post and dispatch |
7c673cae FG |
36 | * handlers with the guarantee that none of those handlers will execute |
37 | * concurrently. | |
38 | * | |
39 | * @par Order of handler invocation | |
40 | * Given: | |
41 | * | |
42 | * @li a strand object @c s | |
43 | * | |
44 | * @li an object @c a meeting completion handler requirements | |
45 | * | |
46 | * @li an object @c a1 which is an arbitrary copy of @c a made by the | |
47 | * implementation | |
48 | * | |
49 | * @li an object @c b meeting completion handler requirements | |
50 | * | |
51 | * @li an object @c b1 which is an arbitrary copy of @c b made by the | |
52 | * implementation | |
53 | * | |
54 | * if any of the following conditions are true: | |
55 | * | |
56 | * @li @c s.post(a) happens-before @c s.post(b) | |
57 | * | |
58 | * @li @c s.post(a) happens-before @c s.dispatch(b), where the latter is | |
59 | * performed outside the strand | |
60 | * | |
61 | * @li @c s.dispatch(a) happens-before @c s.post(b), where the former is | |
62 | * performed outside the strand | |
63 | * | |
64 | * @li @c s.dispatch(a) happens-before @c s.dispatch(b), where both are | |
65 | * performed outside the strand | |
66 | * | |
67 | * then @c asio_handler_invoke(a1, &a1) happens-before | |
68 | * @c asio_handler_invoke(b1, &b1). | |
69 | * | |
70 | * Note that in the following case: | |
71 | * @code async_op_1(..., s.wrap(a)); | |
72 | * async_op_2(..., s.wrap(b)); @endcode | |
73 | * the completion of the first async operation will perform @c s.dispatch(a), | |
74 | * and the second will perform @c s.dispatch(b), but the order in which those | |
75 | * are performed is unspecified. That is, you cannot state whether one | |
76 | * happens-before the other. Therefore none of the above conditions are met and | |
77 | * no ordering guarantee is made. | |
78 | * | |
79 | * @note The implementation makes no guarantee that handlers posted or | |
80 | * dispatched through different @c strand objects will be invoked concurrently. | |
81 | * | |
82 | * @par Thread Safety | |
83 | * @e Distinct @e objects: Safe.@n | |
84 | * @e Shared @e objects: Safe. | |
85 | * | |
86 | * @par Concepts: | |
87 | * Dispatcher. | |
88 | */ | |
b32b8144 | 89 | class io_context::strand |
7c673cae FG |
90 | { |
91 | public: | |
92 | /// Constructor. | |
93 | /** | |
94 | * Constructs the strand. | |
95 | * | |
b32b8144 | 96 | * @param io_context The io_context object that the strand will use to |
7c673cae FG |
97 | * dispatch handlers that are ready to be run. |
98 | */ | |
b32b8144 | 99 | explicit strand(boost::asio::io_context& io_context) |
7c673cae | 100 | : service_(boost::asio::use_service< |
b32b8144 | 101 | boost::asio::detail::strand_service>(io_context)) |
7c673cae FG |
102 | { |
103 | service_.construct(impl_); | |
104 | } | |
105 | ||
106 | /// Destructor. | |
107 | /** | |
108 | * Destroys a strand. | |
109 | * | |
110 | * Handlers posted through the strand that have not yet been invoked will | |
111 | * still be dispatched in a way that meets the guarantee of non-concurrency. | |
112 | */ | |
113 | ~strand() | |
114 | { | |
115 | } | |
116 | ||
b32b8144 FG |
117 | /// Obtain the underlying execution context. |
118 | boost::asio::io_context& context() const BOOST_ASIO_NOEXCEPT | |
119 | { | |
120 | return service_.get_io_context(); | |
121 | } | |
122 | ||
123 | /// Inform the strand that it has some outstanding work to do. | |
124 | /** | |
125 | * The strand delegates this call to its underlying io_context. | |
126 | */ | |
127 | void on_work_started() const BOOST_ASIO_NOEXCEPT | |
128 | { | |
129 | context().get_executor().on_work_started(); | |
130 | } | |
131 | ||
132 | /// Inform the strand that some work is no longer outstanding. | |
133 | /** | |
134 | * The strand delegates this call to its underlying io_context. | |
135 | */ | |
136 | void on_work_finished() const BOOST_ASIO_NOEXCEPT | |
137 | { | |
138 | context().get_executor().on_work_finished(); | |
139 | } | |
140 | ||
141 | /// Request the strand to invoke the given function object. | |
142 | /** | |
143 | * This function is used to ask the strand to execute the given function | |
144 | * object on its underlying io_context. The function object will be executed | |
145 | * inside this function if the strand is not otherwise busy and if the | |
146 | * underlying io_context's executor's @c dispatch() function is also able to | |
147 | * execute the function before returning. | |
148 | * | |
149 | * @param f The function object to be called. The executor will make | |
150 | * a copy of the handler object as required. The function signature of the | |
151 | * function object must be: @code void function(); @endcode | |
152 | * | |
153 | * @param a An allocator that may be used by the executor to allocate the | |
154 | * internal storage needed for function invocation. | |
155 | */ | |
156 | template <typename Function, typename Allocator> | |
157 | void dispatch(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const | |
7c673cae | 158 | { |
b32b8144 FG |
159 | typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f)); |
160 | service_.dispatch(impl_, tmp); | |
161 | (void)a; | |
7c673cae FG |
162 | } |
163 | ||
b32b8144 FG |
164 | #if !defined(BOOST_ASIO_NO_DEPRECATED) |
165 | /// (Deprecated: Use boost::asio::dispatch().) Request the strand to invoke | |
166 | /// the given handler. | |
7c673cae FG |
167 | /** |
168 | * This function is used to ask the strand to execute the given handler. | |
169 | * | |
170 | * The strand object guarantees that handlers posted or dispatched through | |
171 | * the strand will not be executed concurrently. The handler may be executed | |
172 | * inside this function if the guarantee can be met. If this function is | |
173 | * called from within a handler that was posted or dispatched through the same | |
174 | * strand, then the new handler will be executed immediately. | |
175 | * | |
176 | * The strand's guarantee is in addition to the guarantee provided by the | |
b32b8144 FG |
177 | * underlying io_context. The io_context guarantees that the handler will only |
178 | * be called in a thread in which the io_context's run member function is | |
7c673cae FG |
179 | * currently being invoked. |
180 | * | |
181 | * @param handler The handler to be called. The strand will make a copy of the | |
182 | * handler object as required. The function signature of the handler must be: | |
183 | * @code void handler(); @endcode | |
184 | */ | |
11fdf7f2 | 185 | template <typename LegacyCompletionHandler> |
92f5a8d4 | 186 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(LegacyCompletionHandler, void ()) |
11fdf7f2 | 187 | dispatch(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler) |
7c673cae | 188 | { |
92f5a8d4 TL |
189 | return async_initiate<LegacyCompletionHandler, void ()>( |
190 | initiate_dispatch(), handler, this); | |
7c673cae | 191 | } |
b32b8144 FG |
192 | #endif // !defined(BOOST_ASIO_NO_DEPRECATED) |
193 | ||
194 | /// Request the strand to invoke the given function object. | |
195 | /** | |
196 | * This function is used to ask the executor to execute the given function | |
197 | * object. The function object will never be executed inside this function. | |
198 | * Instead, it will be scheduled to run by the underlying io_context. | |
199 | * | |
200 | * @param f The function object to be called. The executor will make | |
201 | * a copy of the handler object as required. The function signature of the | |
202 | * function object must be: @code void function(); @endcode | |
203 | * | |
204 | * @param a An allocator that may be used by the executor to allocate the | |
205 | * internal storage needed for function invocation. | |
206 | */ | |
207 | template <typename Function, typename Allocator> | |
208 | void post(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const | |
209 | { | |
210 | typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f)); | |
211 | service_.post(impl_, tmp); | |
212 | (void)a; | |
213 | } | |
7c673cae | 214 | |
b32b8144 FG |
215 | #if !defined(BOOST_ASIO_NO_DEPRECATED) |
216 | /// (Deprecated: Use boost::asio::post().) Request the strand to invoke the | |
217 | /// given handler and return immediately. | |
7c673cae FG |
218 | /** |
219 | * This function is used to ask the strand to execute the given handler, but | |
220 | * without allowing the strand to call the handler from inside this function. | |
221 | * | |
222 | * The strand object guarantees that handlers posted or dispatched through | |
223 | * the strand will not be executed concurrently. The strand's guarantee is in | |
b32b8144 FG |
224 | * addition to the guarantee provided by the underlying io_context. The |
225 | * io_context guarantees that the handler will only be called in a thread in | |
226 | * which the io_context's run member function is currently being invoked. | |
7c673cae FG |
227 | * |
228 | * @param handler The handler to be called. The strand will make a copy of the | |
229 | * handler object as required. The function signature of the handler must be: | |
230 | * @code void handler(); @endcode | |
231 | */ | |
11fdf7f2 | 232 | template <typename LegacyCompletionHandler> |
92f5a8d4 | 233 | BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(LegacyCompletionHandler, void ()) |
11fdf7f2 | 234 | post(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler) |
7c673cae | 235 | { |
92f5a8d4 TL |
236 | return async_initiate<LegacyCompletionHandler, void ()>( |
237 | initiate_post(), handler, this); | |
7c673cae | 238 | } |
b32b8144 FG |
239 | #endif // !defined(BOOST_ASIO_NO_DEPRECATED) |
240 | ||
241 | /// Request the strand to invoke the given function object. | |
242 | /** | |
243 | * This function is used to ask the executor to execute the given function | |
244 | * object. The function object will never be executed inside this function. | |
245 | * Instead, it will be scheduled to run by the underlying io_context. | |
246 | * | |
247 | * @param f The function object to be called. The executor will make | |
248 | * a copy of the handler object as required. The function signature of the | |
249 | * function object must be: @code void function(); @endcode | |
250 | * | |
251 | * @param a An allocator that may be used by the executor to allocate the | |
252 | * internal storage needed for function invocation. | |
253 | */ | |
254 | template <typename Function, typename Allocator> | |
255 | void defer(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const | |
256 | { | |
257 | typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f)); | |
258 | service_.post(impl_, tmp); | |
259 | (void)a; | |
260 | } | |
7c673cae | 261 | |
b32b8144 FG |
262 | #if !defined(BOOST_ASIO_NO_DEPRECATED) |
263 | /// (Deprecated: Use boost::asio::bind_executor().) Create a new handler that | |
264 | /// automatically dispatches the wrapped handler on the strand. | |
7c673cae FG |
265 | /** |
266 | * This function is used to create a new handler function object that, when | |
267 | * invoked, will automatically pass the wrapped handler to the strand's | |
268 | * dispatch function. | |
269 | * | |
270 | * @param handler The handler to be wrapped. The strand will make a copy of | |
271 | * the handler object as required. The function signature of the handler must | |
272 | * be: @code void handler(A1 a1, ... An an); @endcode | |
273 | * | |
274 | * @return A function object that, when invoked, passes the wrapped handler to | |
275 | * the strand's dispatch function. Given a function object with the signature: | |
276 | * @code R f(A1 a1, ... An an); @endcode | |
277 | * If this function object is passed to the wrap function like so: | |
278 | * @code strand.wrap(f); @endcode | |
279 | * then the return value is a function object with the signature | |
280 | * @code void g(A1 a1, ... An an); @endcode | |
281 | * that, when invoked, executes code equivalent to: | |
282 | * @code strand.dispatch(boost::bind(f, a1, ... an)); @endcode | |
283 | */ | |
284 | template <typename Handler> | |
285 | #if defined(GENERATING_DOCUMENTATION) | |
286 | unspecified | |
287 | #else | |
288 | detail::wrapped_handler<strand, Handler, detail::is_continuation_if_running> | |
289 | #endif | |
290 | wrap(Handler handler) | |
291 | { | |
b32b8144 | 292 | return detail::wrapped_handler<io_context::strand, Handler, |
7c673cae FG |
293 | detail::is_continuation_if_running>(*this, handler); |
294 | } | |
b32b8144 | 295 | #endif // !defined(BOOST_ASIO_NO_DEPRECATED) |
7c673cae FG |
296 | |
297 | /// Determine whether the strand is running in the current thread. | |
298 | /** | |
299 | * @return @c true if the current thread is executing a handler that was | |
300 | * submitted to the strand using post(), dispatch() or wrap(). Otherwise | |
301 | * returns @c false. | |
302 | */ | |
b32b8144 | 303 | bool running_in_this_thread() const BOOST_ASIO_NOEXCEPT |
7c673cae FG |
304 | { |
305 | return service_.running_in_this_thread(impl_); | |
306 | } | |
307 | ||
b32b8144 FG |
308 | /// Compare two strands for equality. |
309 | /** | |
310 | * Two strands are equal if they refer to the same ordered, non-concurrent | |
311 | * state. | |
312 | */ | |
313 | friend bool operator==(const strand& a, const strand& b) BOOST_ASIO_NOEXCEPT | |
314 | { | |
315 | return a.impl_ == b.impl_; | |
316 | } | |
317 | ||
318 | /// Compare two strands for inequality. | |
319 | /** | |
320 | * Two strands are equal if they refer to the same ordered, non-concurrent | |
321 | * state. | |
322 | */ | |
323 | friend bool operator!=(const strand& a, const strand& b) BOOST_ASIO_NOEXCEPT | |
324 | { | |
325 | return a.impl_ != b.impl_; | |
326 | } | |
327 | ||
7c673cae | 328 | private: |
92f5a8d4 TL |
329 | #if !defined(BOOST_ASIO_NO_DEPRECATED) |
330 | struct initiate_dispatch | |
331 | { | |
332 | template <typename LegacyCompletionHandler> | |
333 | void operator()(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler, | |
334 | strand* self) const | |
335 | { | |
336 | // If you get an error on the following line it means that your | |
337 | // handler does not meet the documented type requirements for a | |
338 | // LegacyCompletionHandler. | |
339 | BOOST_ASIO_LEGACY_COMPLETION_HANDLER_CHECK( | |
340 | LegacyCompletionHandler, handler) type_check; | |
341 | ||
342 | detail::non_const_lvalue<LegacyCompletionHandler> handler2(handler); | |
343 | self->service_.dispatch(self->impl_, handler2.value); | |
344 | } | |
345 | }; | |
346 | ||
347 | struct initiate_post | |
348 | { | |
349 | template <typename LegacyCompletionHandler> | |
350 | void operator()(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler, | |
351 | strand* self) const | |
352 | { | |
353 | // If you get an error on the following line it means that your | |
354 | // handler does not meet the documented type requirements for a | |
355 | // LegacyCompletionHandler. | |
356 | BOOST_ASIO_LEGACY_COMPLETION_HANDLER_CHECK( | |
357 | LegacyCompletionHandler, handler) type_check; | |
358 | ||
359 | detail::non_const_lvalue<LegacyCompletionHandler> handler2(handler); | |
360 | self->service_.post(self->impl_, handler2.value); | |
361 | } | |
362 | }; | |
363 | #endif // !defined(BOOST_ASIO_NO_DEPRECATED) | |
364 | ||
7c673cae | 365 | boost::asio::detail::strand_service& service_; |
b32b8144 | 366 | mutable boost::asio::detail::strand_service::implementation_type impl_; |
7c673cae FG |
367 | }; |
368 | ||
7c673cae FG |
369 | } // namespace asio |
370 | } // namespace boost | |
371 | ||
372 | #include <boost/asio/detail/pop_options.hpp> | |
373 | ||
b32b8144 FG |
374 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
375 | ||
376 | #endif // BOOST_ASIO_IO_CONTEXT_STRAND_HPP |