boost/asio/immediate.hpp

0001 //
0002 // immediate.hpp
0003 // ~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2024 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_IMMEDIATE_HPP
0012 #define BOOST_ASIO_IMMEDIATE_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/associated_immediate_executor.hpp>
0020 #include <boost/asio/async_result.hpp>
0021 #include <boost/asio/dispatch.hpp>
0022
0023 #include <boost/asio/detail/push_options.hpp>
0024
0025 namespace boost {
0026 namespace asio {
0027 namespace detail {
0028
0029 template <typename Executor>
0030 class initiate_immediate
0031 {
0032 public:
0033   typedef Executor executor_type;
0034
0035   explicit initiate_immediate(const Executor& ex)
0036     : ex_(ex)
0037   {
0038   }
0039
0040   executor_type get_executor() const noexcept
0041   {
0042     return ex_;
0043   }
0044
0045   template <typename CompletionHandler>
0046   void operator()(CompletionHandler&& handler) const
0047   {
0048     typename associated_immediate_executor<
0049       CompletionHandler, executor_type>::type ex =
0050         (get_associated_immediate_executor)(handler, ex_);
0051     (dispatch)(ex, static_cast<CompletionHandler&&>(handler));
0052   }
0053
0054 private:
0055   Executor ex_;
0056 };
0057
0058 } // namespace detail
0059
0060 /// Launch a trivial asynchronous operation that completes immediately.
0061 /**
0062  * The async_immediate function is intended for use by composed operations,
0063  * which can delegate to this operation in order to implement the correct
0064  * semantics for immediate completion.
0065  *
0066  * @param ex The asynchronous operation's I/O executor.
0067  *
0068  * @param token The completion token.
0069  *
0070  * The completion handler is immediately submitted for execution by calling
0071  * boost::asio::dispatch() on the handler's associated immediate executor.
0072  *
0073  * If the completion handler does not have a customised associated immediate
0074  * executor, then the handler is submitted as if by calling boost::asio::post()
0075  * on the supplied I/O executor.
0076  *
0077  * @par Completion Signature
0078  * @code void() @endcode
0079  */
0080 template <typename Executor,
0081     BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
0082       = default_completion_token_t<Executor>>
0083 inline auto async_immediate(const Executor& ex,
0084     NullaryToken&& token = default_completion_token_t<Executor>(),
0085     constraint_t<
0086       (execution::is_executor<Executor>::value
0087           && can_require<Executor, execution::blocking_t::never_t>::value)
0088         || is_executor<Executor>::value
0089     > = 0)
0090   -> decltype(
0091     async_initiate<NullaryToken, void()>(
0092       declval<detail::initiate_immediate<Executor>>(), token))
0093 {
0094   return async_initiate<NullaryToken, void()>(
0095       detail::initiate_immediate<Executor>(ex), token);
0096 }
0097
0098 /// Launch a trivial asynchronous operation that completes immediately.
0099 /**
0100  * The async_immediate function is intended for use by composed operations,
0101  * which can delegate to this operation in order to implement the correct
0102  * semantics for immediate completion.
0103  *
0104  * @param ex The execution context used to obtain the asynchronous operation's
0105  * I/O executor.
0106  *
0107  * @param token The completion token.
0108  *
0109  * The completion handler is immediately submitted for execution by calling
0110  * boost::asio::dispatch() on the handler's associated immediate executor.
0111  *
0112  * If the completion handler does not have a customised associated immediate
0113  * executor, then the handler is submitted as if by calling boost::asio::post()
0114  * on the I/O executor obtained from the supplied execution context.
0115  *
0116  * @par Completion Signature
0117  * @code void() @endcode
0118  */
0119 template <typename ExecutionContext,
0120     BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
0121       = default_completion_token_t<typename ExecutionContext::executor_type>>
0122 inline auto async_immediate(ExecutionContext& ctx,
0123     NullaryToken&& token = default_completion_token_t<
0124       typename ExecutionContext::executor_type>(),
0125     constraint_t<
0126       is_convertible<ExecutionContext&, execution_context&>::value
0127     > = 0)
0128   -> decltype(
0129     async_initiate<NullaryToken, void()>(
0130       declval<detail::initiate_immediate<
0131         typename ExecutionContext::executor_type>>(), token))
0132 {
0133   return async_initiate<NullaryToken, void()>(
0134       detail::initiate_immediate<
0135         typename ExecutionContext::executor_type>(
0136           ctx.get_executor()), token);
0137 }
0138
0139 } // namespace asio
0140 } // namespace boost
0141
0142 #include <boost/asio/detail/pop_options.hpp>
0143
0144 #endif // BOOST_ASIO_IMMEDIATE_HPP