boost/asio/post.hpp

0001 //
0002 // post.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_POST_HPP
0012 #define BOOST_ASIO_POST_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_post.hpp>
0021 #include <boost/asio/detail/type_traits.hpp>
0022 #include <boost/asio/execution_context.hpp>
0023 #include <boost/asio/execution/blocking.hpp>
0024 #include <boost/asio/execution/executor.hpp>
0025 #include <boost/asio/is_executor.hpp>
0026 #include <boost/asio/require.hpp>
0027
0028 #include <boost/asio/detail/push_options.hpp>
0029
0030 namespace boost {
0031 namespace asio {
0032
0033 /// Submits a completion token or function object for execution.
0034 /**
0035  * This function submits an object for execution using the object's associated
0036  * executor. The function object is queued for execution, and is never called
0037  * from the current thread prior to returning from <tt>post()</tt>.
0038  *
0039  * The use of @c post(), rather than @ref defer(), indicates the caller's
0040  * preference that the function object be eagerly queued for execution.
0041  *
0042  * @param token The @ref completion_token that will be used to produce a
0043  * completion handler. The function signature of the completion handler must be:
0044  * @code void handler(); @endcode
0045  *
0046  * @returns This function returns <tt>async_initiate<NullaryToken,
0047  * void()>(Init{}, token)</tt>, where @c Init is a function object type defined
0048  * as:
0049  *
0050  * @code class Init
0051  * {
0052  * public:
0053  *   template <typename CompletionHandler>
0054  *     void operator()(CompletionHandler&& completion_handler) const;
0055  * }; @endcode
0056  *
0057  * The function call operator of @c Init:
0058  *
0059  * @li Obtains the handler's associated executor object @c ex of type @c Ex by
0060  * performing @code auto ex = get_associated_executor(handler); @endcode
0061  *
0062  * @li Obtains the handler's associated allocator object @c alloc by performing
0063  * @code auto alloc = get_associated_allocator(handler); @endcode
0064  *
0065  * @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs
0066  * @code prefer(
0067  *     require(ex, execution::blocking.never),
0068  *     execution::relationship.fork,
0069  *     execution::allocator(alloc)
0070  *   ).execute(std::forward<CompletionHandler>(completion_handler)); @endcode
0071  *
0072  * @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs
0073  * @code ex.post(
0074  *     std::forward<CompletionHandler>(completion_handler),
0075  *     alloc); @endcode
0076  *
0077  * @par Completion Signature
0078  * @code void() @endcode
0079  */
0080 template <BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken>
0081 inline auto post(NullaryToken&& token)
0082   -> decltype(
0083     async_initiate<NullaryToken, void()>(
0084       declval<detail::initiate_post>(), token))
0085 {
0086   return async_initiate<NullaryToken, void()>(
0087       detail::initiate_post(), token);
0088 }
0089
0090 /// Submits a completion token or function object for execution.
0091 /**
0092  * This function submits an object for execution using the specified executor.
0093  * The function object is queued for execution, and is never called from the
0094  * current thread prior to returning from <tt>post()</tt>.
0095  *
0096  * The use of @c post(), rather than @ref defer(), indicates the caller's
0097  * preference that the function object be eagerly queued for execution.
0098  *
0099  * @param ex The target executor.
0100  *
0101  * @param token The @ref completion_token that will be used to produce a
0102  * completion handler. The function signature of the completion handler must be:
0103  * @code void handler(); @endcode
0104  *
0105  * @returns This function returns <tt>async_initiate<NullaryToken,
0106  * void()>(Init{ex}, token)</tt>, where @c Init is a function object type
0107  * defined as:
0108  *
0109  * @code class Init
0110  * {
0111  * public:
0112  *   using executor_type = Executor;
0113  *   explicit Init(const Executor& ex) : ex_(ex) {}
0114  *   executor_type get_executor() const noexcept { return ex_; }
0115  *   template <typename CompletionHandler>
0116  *     void operator()(CompletionHandler&& completion_handler) const;
0117  * private:
0118  *   Executor ex_; // exposition only
0119  * }; @endcode
0120  *
0121  * The function call operator of @c Init:
0122  *
0123  * @li Obtains the handler's associated executor object @c ex1 of type @c Ex1 by
0124  * performing @code auto ex1 = get_associated_executor(handler, ex); @endcode
0125  *
0126  * @li Obtains the handler's associated allocator object @c alloc by performing
0127  * @code auto alloc = get_associated_allocator(handler); @endcode
0128  *
0129  * @li If <tt>execution::is_executor<Ex1>::value</tt> is true, constructs a
0130  * function object @c f with a member @c executor_ that is initialised with
0131  * <tt>prefer(ex1, execution::outstanding_work.tracked)</tt>, a member @c
0132  * handler_ that is a decay-copy of @c completion_handler, and a function call
0133  * operator that performs:
0134  * @code auto a = get_associated_allocator(handler_);
0135  * prefer(executor_, execution::allocator(a)).execute(std::move(handler_));
0136  * @endcode
0137  *
0138  * @li If <tt>execution::is_executor<Ex1>::value</tt> is false, constructs a
0139  * function object @c f with a member @c work_ that is initialised with
0140  * <tt>make_work_guard(ex1)</tt>, a member @c handler_ that is a decay-copy of
0141  * @c completion_handler, and a function call operator that performs:
0142  * @code auto a = get_associated_allocator(handler_);
0143  * work_.get_executor().dispatch(std::move(handler_), a);
0144  * work_.reset(); @endcode
0145  *
0146  * @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs
0147  * @code prefer(
0148  *     require(ex, execution::blocking.never),
0149  *     execution::relationship.fork,
0150  *     execution::allocator(alloc)
0151  *   ).execute(std::move(f)); @endcode
0152  *
0153  * @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs
0154  * @code ex.post(std::move(f), alloc); @endcode
0155  *
0156  * @par Completion Signature
0157  * @code void() @endcode
0158  */
0159 template <typename Executor,
0160     BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
0161       = default_completion_token_t<Executor>>
0162 inline auto post(const Executor& ex,
0163     NullaryToken&& token = default_completion_token_t<Executor>(),
0164     constraint_t<
0165       (execution::is_executor<Executor>::value
0166           && can_require<Executor, execution::blocking_t::never_t>::value)
0167         || is_executor<Executor>::value
0168     > = 0)
0169   -> decltype(
0170     async_initiate<NullaryToken, void()>(
0171       declval<detail::initiate_post_with_executor<Executor>>(), token))
0172 {
0173   return async_initiate<NullaryToken, void()>(
0174       detail::initiate_post_with_executor<Executor>(ex), token);
0175 }
0176
0177 /// Submits a completion token or function object for execution.
0178 /**
0179  * @param ctx An execution context, from which the target executor is obtained.
0180  *
0181  * @param token The @ref completion_token that will be used to produce a
0182  * completion handler. The function signature of the completion handler must be:
0183  * @code void handler(); @endcode
0184  *
0185  * @returns <tt>post(ctx.get_executor(), forward<NullaryToken>(token))</tt>.
0186  *
0187  * @par Completion Signature
0188  * @code void() @endcode
0189  */
0190 template <typename ExecutionContext,
0191     BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
0192       = default_completion_token_t<typename ExecutionContext::executor_type>>
0193 inline auto post(ExecutionContext& ctx,
0194     NullaryToken&& token = default_completion_token_t<
0195       typename ExecutionContext::executor_type>(),
0196     constraint_t<
0197       is_convertible<ExecutionContext&, execution_context&>::value
0198     > = 0)
0199   -> decltype(
0200     async_initiate<NullaryToken, void()>(
0201       declval<detail::initiate_post_with_executor<
0202         typename ExecutionContext::executor_type>>(), token))
0203 {
0204   return async_initiate<NullaryToken, void()>(
0205       detail::initiate_post_with_executor<
0206         typename ExecutionContext::executor_type>(
0207           ctx.get_executor()), token);
0208 }
0209
0210 } // namespace asio
0211 } // namespace boost
0212
0213 #include <boost/asio/detail/pop_options.hpp>
0214
0215 #endif // BOOST_ASIO_POST_HPP