boost/asio/dispatch.hpp

0001 //
0002 // dispatch.hpp
0003 // ~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2025 Christopher M. Kohlhoff (chris at kohlhoff dot com)
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009 //
0010
0011 #ifndef BOOST_ASIO_DISPATCH_HPP
0012 #define BOOST_ASIO_DISPATCH_HPP
0013
0014 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
0015 # pragma once
0016 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
0017
0018 #include <boost/asio/detail/config.hpp>
0019 #include <boost/asio/async_result.hpp>
0020 #include <boost/asio/detail/initiate_dispatch.hpp>
0021 #include <boost/asio/detail/type_traits.hpp>
0022 #include <boost/asio/execution_context.hpp>
0023 #include <boost/asio/execution/executor.hpp>
0024 #include <boost/asio/is_executor.hpp>
0025
0026 #include <boost/asio/detail/push_options.hpp>
0027
0028 namespace boost {
0029 namespace asio {
0030
0031 /// Submits a completion token or function object for execution.
0032 /**
0033  * This function submits an object for execution using the object's associated
0034  * executor. The function object may be called from the current thread prior to
0035  * returning from <tt>dispatch()</tt>. Otherwise, it is queued for execution.
0036  *
0037  * @param token The @ref completion_token that will be used to produce a
0038  * completion handler. The function signature of the completion handler must be:
0039  * @code void handler(); @endcode
0040  *
0041  * @returns This function returns <tt>async_initiate<NullaryToken,
0042  * void()>(Init{}, token)</tt>, where @c Init is a function object type defined
0043  * as:
0044  *
0045  * @code class Init
0046  * {
0047  * public:
0048  *   template <typename CompletionHandler>
0049  *     void operator()(CompletionHandler&& completion_handler) const;
0050  * }; @endcode
0051  *
0052  * The function call operator of @c Init:
0053  *
0054  * @li Obtains the handler's associated executor object @c ex of type @c Ex by
0055  * performing @code auto ex = get_associated_executor(handler); @endcode
0056  *
0057  * @li Obtains the handler's associated allocator object @c alloc by performing
0058  * @code auto alloc = get_associated_allocator(handler); @endcode
0059  *
0060  * @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs
0061  * @code prefer(ex, execution::allocator(alloc)).execute(
0062  *     std::forward<CompletionHandler>(completion_handler)); @endcode
0063  *
0064  * @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs
0065  * @code ex.dispatch(
0066  *     std::forward<CompletionHandler>(completion_handler),
0067  *     alloc); @endcode
0068  *
0069  * @par Completion Signature
0070  * @code void() @endcode
0071  */
0072 template <BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken>
0073 inline auto dispatch(NullaryToken&& token)
0074   -> decltype(
0075     async_initiate<NullaryToken, void()>(
0076       declval<detail::initiate_dispatch>(), token))
0077 {
0078   return async_initiate<NullaryToken, void()>(
0079       detail::initiate_dispatch(), token);
0080 }
0081
0082 /// Submits a completion token or function object for execution.
0083 /**
0084  * This function submits an object for execution using the specified executor.
0085  * The function object may be called from the current thread prior to returning
0086  * from <tt>dispatch()</tt>. Otherwise, it is queued for execution.
0087  *
0088  * @param ex The target executor.
0089  *
0090  * @param token The @ref completion_token that will be used to produce a
0091  * completion handler. The function signature of the completion handler must be:
0092  * @code void handler(); @endcode
0093  *
0094  * @returns This function returns <tt>async_initiate<NullaryToken,
0095  * void()>(Init{ex}, token)</tt>, where @c Init is a function object type
0096  * defined as:
0097  *
0098  * @code class Init
0099  * {
0100  * public:
0101  *   using executor_type = Executor;
0102  *   explicit Init(const Executor& ex) : ex_(ex) {}
0103  *   executor_type get_executor() const noexcept { return ex_; }
0104  *   template <typename CompletionHandler>
0105  *     void operator()(CompletionHandler&& completion_handler) const;
0106  * private:
0107  *   Executor ex_; // exposition only
0108  * }; @endcode
0109  *
0110  * The function call operator of @c Init:
0111  *
0112  * @li Obtains the handler's associated executor object @c ex1 of type @c Ex1 by
0113  * performing @code auto ex1 = get_associated_executor(handler, ex); @endcode
0114  *
0115  * @li Obtains the handler's associated allocator object @c alloc by performing
0116  * @code auto alloc = get_associated_allocator(handler); @endcode
0117  *
0118  * @li If <tt>execution::is_executor<Ex1>::value</tt> is true, constructs a
0119  * function object @c f with a member @c executor_ that is initialised with
0120  * <tt>prefer(ex1, execution::outstanding_work.tracked)</tt>, a member @c
0121  * handler_ that is a decay-copy of @c completion_handler, and a function call
0122  * operator that performs:
0123  * @code auto a = get_associated_allocator(handler_);
0124  * prefer(executor_, execution::allocator(a)).execute(std::move(handler_));
0125  * @endcode
0126  *
0127  * @li If <tt>execution::is_executor<Ex1>::value</tt> is false, constructs a
0128  * function object @c f with a member @c work_ that is initialised with
0129  * <tt>make_work_guard(ex1)</tt>, a member @c handler_ that is a decay-copy of
0130  * @c completion_handler, and a function call operator that performs:
0131  * @code auto a = get_associated_allocator(handler_);
0132  * work_.get_executor().dispatch(std::move(handler_), a);
0133  * work_.reset(); @endcode
0134  *
0135  * @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs
0136  * @code prefer(ex, execution::allocator(alloc)).execute(std::move(f)); @endcode
0137  *
0138  * @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs
0139  * @code ex.dispatch(std::move(f), alloc); @endcode
0140  *
0141  * @par Completion Signature
0142  * @code void() @endcode
0143  */
0144 template <typename Executor,
0145     BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
0146       = default_completion_token_t<Executor>>
0147 inline auto dispatch(const Executor& ex,
0148     NullaryToken&& token = default_completion_token_t<Executor>(),
0149     constraint_t<
0150       execution::is_executor<Executor>::value || is_executor<Executor>::value
0151     > = 0)
0152   -> decltype(
0153     async_initiate<NullaryToken, void()>(
0154       declval<detail::initiate_dispatch_with_executor<Executor>>(), token))
0155 {
0156   return async_initiate<NullaryToken, void()>(
0157       detail::initiate_dispatch_with_executor<Executor>(ex), token);
0158 }
0159
0160 /// Submits a completion token or function object for execution.
0161 /**
0162  * @param ctx An execution context, from which the target executor is obtained.
0163  *
0164  * @param token The @ref completion_token that will be used to produce a
0165  * completion handler. The function signature of the completion handler must be:
0166  * @code void handler(); @endcode
0167  *
0168  * @returns <tt>dispatch(ctx.get_executor(),
0169  * forward<NullaryToken>(token))</tt>.
0170  *
0171  * @par Completion Signature
0172  * @code void() @endcode
0173  */
0174 template <typename ExecutionContext,
0175     BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
0176       = default_completion_token_t<typename ExecutionContext::executor_type>>
0177 inline auto dispatch(ExecutionContext& ctx,
0178     NullaryToken&& token = default_completion_token_t<
0179       typename ExecutionContext::executor_type>(),
0180     constraint_t<
0181       is_convertible<ExecutionContext&, execution_context&>::value
0182     > = 0)
0183   -> decltype(
0184     async_initiate<NullaryToken, void()>(
0185       declval<detail::initiate_dispatch_with_executor<
0186         typename ExecutionContext::executor_type>>(), token))
0187 {
0188   return async_initiate<NullaryToken, void()>(
0189       detail::initiate_dispatch_with_executor<
0190         typename ExecutionContext::executor_type>(
0191           ctx.get_executor()), token);
0192 }
0193
0194 } // namespace asio
0195 } // namespace boost
0196
0197 #include <boost/asio/detail/pop_options.hpp>
0198
0199 #endif // BOOST_ASIO_DISPATCH_HPP