2 // io_context_strand.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_IO_CONTEXT_STRAND_HPP
12 #define BOOST_ASIO_IO_CONTEXT_STRAND_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #if !defined(BOOST_ASIO_NO_EXTENSIONS) \
21 && !defined(BOOST_ASIO_NO_TS_EXECUTORS)
23 #include <boost/asio/async_result.hpp>
24 #include <boost/asio/detail/handler_type_requirements.hpp>
25 #include <boost/asio/detail/strand_service.hpp>
26 #include <boost/asio/detail/wrapped_handler.hpp>
27 #include <boost/asio/io_context.hpp>
29 #include <boost/asio/detail/push_options.hpp>
34 /// Provides serialised handler execution.
36 * The io_context::strand class provides the ability to post and dispatch
37 * handlers with the guarantee that none of those handlers will execute
40 * @par Order of handler invocation
43 * @li a strand object @c s
45 * @li an object @c a meeting completion handler requirements
47 * @li an object @c a1 which is an arbitrary copy of @c a made by the
50 * @li an object @c b meeting completion handler requirements
52 * @li an object @c b1 which is an arbitrary copy of @c b made by the
55 * if any of the following conditions are true:
57 * @li @c s.post(a) happens-before @c s.post(b)
59 * @li @c s.post(a) happens-before @c s.dispatch(b), where the latter is
60 * performed outside the strand
62 * @li @c s.dispatch(a) happens-before @c s.post(b), where the former is
63 * performed outside the strand
65 * @li @c s.dispatch(a) happens-before @c s.dispatch(b), where both are
66 * performed outside the strand
68 * then @c asio_handler_invoke(a1, &a1) happens-before
69 * @c asio_handler_invoke(b1, &b1).
71 * Note that in the following case:
72 * @code async_op_1(..., s.wrap(a));
73 * async_op_2(..., s.wrap(b)); @endcode
74 * the completion of the first async operation will perform @c s.dispatch(a),
75 * and the second will perform @c s.dispatch(b), but the order in which those
76 * are performed is unspecified. That is, you cannot state whether one
77 * happens-before the other. Therefore none of the above conditions are met and
78 * no ordering guarantee is made.
80 * @note The implementation makes no guarantee that handlers posted or
81 * dispatched through different @c strand objects will be invoked concurrently.
84 * @e Distinct @e objects: Safe.@n
85 * @e Shared @e objects: Safe.
90 class io_context::strand
95 * Constructs the strand.
97 * @param io_context The io_context object that the strand will use to
98 * dispatch handlers that are ready to be run.
100 explicit strand(boost::asio::io_context& io_context)
101 : service_(boost::asio::use_service<
102 boost::asio::detail::strand_service>(io_context))
104 service_.construct(impl_);
111 * Handlers posted through the strand that have not yet been invoked will
112 * still be dispatched in a way that meets the guarantee of non-concurrency.
118 /// Obtain the underlying execution context.
119 boost::asio::io_context& context() const BOOST_ASIO_NOEXCEPT
121 return service_.get_io_context();
124 /// Inform the strand that it has some outstanding work to do.
126 * The strand delegates this call to its underlying io_context.
128 void on_work_started() const BOOST_ASIO_NOEXCEPT
130 context().get_executor().on_work_started();
133 /// Inform the strand that some work is no longer outstanding.
135 * The strand delegates this call to its underlying io_context.
137 void on_work_finished() const BOOST_ASIO_NOEXCEPT
139 context().get_executor().on_work_finished();
142 /// Request the strand to invoke the given function object.
144 * This function is used to ask the strand to execute the given function
145 * object on its underlying io_context. The function object will be executed
146 * inside this function if the strand is not otherwise busy and if the
147 * underlying io_context's executor's @c dispatch() function is also able to
148 * execute the function before returning.
150 * @param f The function object to be called. The executor will make
151 * a copy of the handler object as required. The function signature of the
152 * function object must be: @code void function(); @endcode
154 * @param a An allocator that may be used by the executor to allocate the
155 * internal storage needed for function invocation.
157 template <typename Function, typename Allocator>
158 void dispatch(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const
160 typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f));
161 service_.dispatch(impl_, tmp);
165 #if !defined(BOOST_ASIO_NO_DEPRECATED)
166 /// (Deprecated: Use boost::asio::dispatch().) Request the strand to invoke
167 /// the given handler.
169 * This function is used to ask the strand to execute the given handler.
171 * The strand object guarantees that handlers posted or dispatched through
172 * the strand will not be executed concurrently. The handler may be executed
173 * inside this function if the guarantee can be met. If this function is
174 * called from within a handler that was posted or dispatched through the same
175 * strand, then the new handler will be executed immediately.
177 * The strand's guarantee is in addition to the guarantee provided by the
178 * underlying io_context. The io_context guarantees that the handler will only
179 * be called in a thread in which the io_context's run member function is
180 * currently being invoked.
182 * @param handler The handler to be called. The strand will make a copy of the
183 * handler object as required. The function signature of the handler must be:
184 * @code void handler(); @endcode
186 template <typename LegacyCompletionHandler>
187 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(LegacyCompletionHandler, void ())
188 dispatch(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
190 return async_initiate<LegacyCompletionHandler, void ()>(
191 initiate_dispatch(), handler, this);
193 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
195 /// Request the strand to invoke the given function object.
197 * This function is used to ask the executor to execute the given function
198 * object. The function object will never be executed inside this function.
199 * Instead, it will be scheduled to run by the underlying io_context.
201 * @param f The function object to be called. The executor will make
202 * a copy of the handler object as required. The function signature of the
203 * function object must be: @code void function(); @endcode
205 * @param a An allocator that may be used by the executor to allocate the
206 * internal storage needed for function invocation.
208 template <typename Function, typename Allocator>
209 void post(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const
211 typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f));
212 service_.post(impl_, tmp);
216 #if !defined(BOOST_ASIO_NO_DEPRECATED)
217 /// (Deprecated: Use boost::asio::post().) Request the strand to invoke the
218 /// given handler and return immediately.
220 * This function is used to ask the strand to execute the given handler, but
221 * without allowing the strand to call the handler from inside this function.
223 * The strand object guarantees that handlers posted or dispatched through
224 * the strand will not be executed concurrently. The strand's guarantee is in
225 * addition to the guarantee provided by the underlying io_context. The
226 * io_context guarantees that the handler will only be called in a thread in
227 * which the io_context's run member function is currently being invoked.
229 * @param handler The handler to be called. The strand will make a copy of the
230 * handler object as required. The function signature of the handler must be:
231 * @code void handler(); @endcode
233 template <typename LegacyCompletionHandler>
234 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(LegacyCompletionHandler, void ())
235 post(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
237 return async_initiate<LegacyCompletionHandler, void ()>(
238 initiate_post(), handler, this);
240 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
242 /// Request the strand to invoke the given function object.
244 * This function is used to ask the executor to execute the given function
245 * object. The function object will never be executed inside this function.
246 * Instead, it will be scheduled to run by the underlying io_context.
248 * @param f The function object to be called. The executor will make
249 * a copy of the handler object as required. The function signature of the
250 * function object must be: @code void function(); @endcode
252 * @param a An allocator that may be used by the executor to allocate the
253 * internal storage needed for function invocation.
255 template <typename Function, typename Allocator>
256 void defer(BOOST_ASIO_MOVE_ARG(Function) f, const Allocator& a) const
258 typename decay<Function>::type tmp(BOOST_ASIO_MOVE_CAST(Function)(f));
259 service_.post(impl_, tmp);
263 #if !defined(BOOST_ASIO_NO_DEPRECATED)
264 /// (Deprecated: Use boost::asio::bind_executor().) Create a new handler that
265 /// automatically dispatches the wrapped handler on the strand.
267 * This function is used to create a new handler function object that, when
268 * invoked, will automatically pass the wrapped handler to the strand's
271 * @param handler The handler to be wrapped. The strand will make a copy of
272 * the handler object as required. The function signature of the handler must
273 * be: @code void handler(A1 a1, ... An an); @endcode
275 * @return A function object that, when invoked, passes the wrapped handler to
276 * the strand's dispatch function. Given a function object with the signature:
277 * @code R f(A1 a1, ... An an); @endcode
278 * If this function object is passed to the wrap function like so:
279 * @code strand.wrap(f); @endcode
280 * then the return value is a function object with the signature
281 * @code void g(A1 a1, ... An an); @endcode
282 * that, when invoked, executes code equivalent to:
283 * @code strand.dispatch(boost::bind(f, a1, ... an)); @endcode
285 template <typename Handler>
286 #if defined(GENERATING_DOCUMENTATION)
289 detail::wrapped_handler<strand, Handler, detail::is_continuation_if_running>
291 wrap(Handler handler)
293 return detail::wrapped_handler<io_context::strand, Handler,
294 detail::is_continuation_if_running>(*this, handler);
296 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
298 /// Determine whether the strand is running in the current thread.
300 * @return @c true if the current thread is executing a handler that was
301 * submitted to the strand using post(), dispatch() or wrap(). Otherwise
304 bool running_in_this_thread() const BOOST_ASIO_NOEXCEPT
306 return service_.running_in_this_thread(impl_);
309 /// Compare two strands for equality.
311 * Two strands are equal if they refer to the same ordered, non-concurrent
314 friend bool operator==(const strand& a, const strand& b) BOOST_ASIO_NOEXCEPT
316 return a.impl_ == b.impl_;
319 /// Compare two strands for inequality.
321 * Two strands are equal if they refer to the same ordered, non-concurrent
324 friend bool operator!=(const strand& a, const strand& b) BOOST_ASIO_NOEXCEPT
326 return a.impl_ != b.impl_;
330 #if !defined(BOOST_ASIO_NO_DEPRECATED)
331 struct initiate_dispatch
333 template <typename LegacyCompletionHandler>
334 void operator()(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler,
337 // If you get an error on the following line it means that your
338 // handler does not meet the documented type requirements for a
339 // LegacyCompletionHandler.
340 BOOST_ASIO_LEGACY_COMPLETION_HANDLER_CHECK(
341 LegacyCompletionHandler, handler) type_check;
343 detail::non_const_lvalue<LegacyCompletionHandler> handler2(handler);
344 self->service_.dispatch(self->impl_, handler2.value);
350 template <typename LegacyCompletionHandler>
351 void operator()(BOOST_ASIO_MOVE_ARG(LegacyCompletionHandler) handler,
354 // If you get an error on the following line it means that your
355 // handler does not meet the documented type requirements for a
356 // LegacyCompletionHandler.
357 BOOST_ASIO_LEGACY_COMPLETION_HANDLER_CHECK(
358 LegacyCompletionHandler, handler) type_check;
360 detail::non_const_lvalue<LegacyCompletionHandler> handler2(handler);
361 self->service_.post(self->impl_, handler2.value);
364 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
366 boost::asio::detail::strand_service& service_;
367 mutable boost::asio::detail::strand_service::implementation_type impl_;
373 #include <boost/asio/detail/pop_options.hpp>
375 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
376 // && !defined(BOOST_ASIO_NO_TS_EXECUTORS)
378 #endif // BOOST_ASIO_IO_CONTEXT_STRAND_HPP