boost/asio/cancel_after.hpp

0001 //
0002 // cancel_after.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_CANCEL_AFTER_HPP
0012 #define BOOST_ASIO_CANCEL_AFTER_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/basic_waitable_timer.hpp>
0020 #include <boost/asio/cancellation_type.hpp>
0021 #include <boost/asio/detail/chrono.hpp>
0022 #include <boost/asio/detail/type_traits.hpp>
0023 #include <boost/asio/wait_traits.hpp>
0024
0025 #include <boost/asio/detail/push_options.hpp>
0026
0027 namespace boost {
0028 namespace asio {
0029
0030 /// A @ref completion_token adapter that cancels an operation after a timeout.
0031 /**
0032  * The cancel_after_t class is used to indicate that an asynchronous operation
0033  * should be cancelled if not complete before the specified duration has
0034  * elapsed.
0035  */
0036 template <typename CompletionToken, typename Clock,
0037     typename WaitTraits = boost::asio::wait_traits<Clock>>
0038 class cancel_after_t
0039 {
0040 public:
0041   /// Constructor.
0042   template <typename T>
0043   cancel_after_t(T&& completion_token, const typename Clock::duration& timeout,
0044       cancellation_type_t cancel_type = cancellation_type::terminal)
0045     : token_(static_cast<T&&>(completion_token)),
0046       timeout_(timeout),
0047       cancel_type_(cancel_type)
0048   {
0049   }
0050
0051 //private:
0052   CompletionToken token_;
0053   typename Clock::duration timeout_;
0054   cancellation_type_t cancel_type_;
0055 };
0056
0057 /// A @ref completion_token adapter that cancels an operation after a timeout.
0058 /**
0059  * The cancel_after_timer class is used to indicate that an asynchronous
0060  * operation should be cancelled if not complete before the specified duration
0061  * has elapsed.
0062  */
0063 template <typename CompletionToken, typename Clock,
0064     typename WaitTraits = boost::asio::wait_traits<Clock>,
0065     typename Executor = any_io_executor>
0066 class cancel_after_timer
0067 {
0068 public:
0069   /// Constructor.
0070   template <typename T>
0071   cancel_after_timer(T&& completion_token,
0072       basic_waitable_timer<Clock, WaitTraits, Executor>& timer,
0073       const typename Clock::duration& timeout,
0074       cancellation_type_t cancel_type = cancellation_type::terminal)
0075     : token_(static_cast<T&&>(completion_token)),
0076       timer_(timer),
0077       timeout_(timeout),
0078       cancel_type_(cancel_type)
0079   {
0080   }
0081
0082 //private:
0083   CompletionToken token_;
0084   basic_waitable_timer<Clock, WaitTraits, Executor>& timer_;
0085   typename Clock::duration timeout_;
0086   cancellation_type_t cancel_type_;
0087 };
0088
0089 /// A function object type that adapts a @ref completion_token to cancel an
0090 /// operation after a timeout.
0091 /**
0092  * May also be used directly as a completion token, in which case it adapts the
0093  * asynchronous operation's default completion token (or boost::asio::deferred
0094  * if no default is available).
0095  */
0096 template <typename Clock, typename WaitTraits = boost::asio::wait_traits<Clock>>
0097 class partial_cancel_after
0098 {
0099 public:
0100   /// Constructor that specifies the timeout duration and cancellation type.
0101   explicit partial_cancel_after(const typename Clock::duration& timeout,
0102       cancellation_type_t cancel_type = cancellation_type::terminal)
0103     : timeout_(timeout),
0104       cancel_type_(cancel_type)
0105   {
0106   }
0107
0108   /// Adapt a @ref completion_token to specify that the completion handler
0109   /// arguments should be combined into a single tuple argument.
0110   template <typename CompletionToken>
0111   BOOST_ASIO_NODISCARD inline
0112   cancel_after_t<decay_t<CompletionToken>, Clock, WaitTraits>
0113   operator()(CompletionToken&& completion_token) const
0114   {
0115     return cancel_after_t<decay_t<CompletionToken>, Clock, WaitTraits>(
0116         static_cast<CompletionToken&&>(completion_token),
0117         timeout_, cancel_type_);
0118   }
0119
0120 //private:
0121   typename Clock::duration timeout_;
0122   cancellation_type_t cancel_type_;
0123 };
0124
0125 /// A function object type that adapts a @ref completion_token to cancel an
0126 /// operation after a timeout.
0127 /**
0128  * May also be used directly as a completion token, in which case it adapts the
0129  * asynchronous operation's default completion token (or boost::asio::deferred
0130  * if no default is available).
0131  */
0132 template <typename Clock, typename WaitTraits = boost::asio::wait_traits<Clock>,
0133     typename Executor = any_io_executor>
0134 class partial_cancel_after_timer
0135 {
0136 public:
0137   /// Constructor that specifies the timeout duration and cancellation type.
0138   explicit partial_cancel_after_timer(
0139       basic_waitable_timer<Clock, WaitTraits, Executor>& timer,
0140       const typename Clock::duration& timeout,
0141       cancellation_type_t cancel_type = cancellation_type::terminal)
0142     : timer_(timer),
0143       timeout_(timeout),
0144       cancel_type_(cancel_type)
0145   {
0146   }
0147
0148   /// Adapt a @ref completion_token to specify that the completion handler
0149   /// arguments should be combined into a single tuple argument.
0150   template <typename CompletionToken>
0151   BOOST_ASIO_NODISCARD inline
0152   cancel_after_timer<decay_t<CompletionToken>, Clock, WaitTraits, Executor>
0153   operator()(CompletionToken&& completion_token) const
0154   {
0155     return cancel_after_timer<decay_t<CompletionToken>,
0156       Clock, WaitTraits, Executor>(
0157         static_cast<CompletionToken&&>(completion_token),
0158         timeout_, cancel_type_);
0159   }
0160
0161 //private:
0162   basic_waitable_timer<Clock, WaitTraits, Executor>& timer_;
0163   typename Clock::duration timeout_;
0164   cancellation_type_t cancel_type_;
0165 };
0166
0167 /// Create a partial completion token adapter that cancels an operation if not
0168 /// complete before the specified relative timeout has elapsed.
0169 /**
0170  * @par Thread Safety
0171  * When an asynchronous operation is used with cancel_after, a timer async_wait
0172  * operation is performed in parallel to the main operation. If this parallel
0173  * async_wait completes first, a cancellation request is emitted to cancel the
0174  * main operation. Consequently, the application must ensure that the
0175  * asynchronous operation is performed within an implicit or explicit strand.
0176  */
0177 template <typename Rep, typename Period>
0178 BOOST_ASIO_NODISCARD inline partial_cancel_after<chrono::steady_clock>
0179 cancel_after(const chrono::duration<Rep, Period>& timeout,
0180     cancellation_type_t cancel_type = cancellation_type::terminal)
0181 {
0182   return partial_cancel_after<chrono::steady_clock>(timeout, cancel_type);
0183 }
0184
0185 /// Create a partial completion token adapter that cancels an operation if not
0186 /// complete before the specified relative timeout has elapsed.
0187 /**
0188  * @par Thread Safety
0189  * When an asynchronous operation is used with cancel_after, a timer async_wait
0190  * operation is performed in parallel to the main operation. If this parallel
0191  * async_wait completes first, a cancellation request is emitted to cancel the
0192  * main operation. Consequently, the application must ensure that the
0193  * asynchronous operation is performed within an implicit or explicit strand.
0194  */
0195 template <typename Clock, typename WaitTraits,
0196     typename Executor, typename Rep, typename Period>
0197 BOOST_ASIO_NODISCARD inline
0198 partial_cancel_after_timer<Clock, WaitTraits, Executor>
0199 cancel_after(basic_waitable_timer<Clock, WaitTraits, Executor>& timer,
0200     const chrono::duration<Rep, Period>& timeout,
0201     cancellation_type_t cancel_type = cancellation_type::terminal)
0202 {
0203   return partial_cancel_after_timer<Clock, WaitTraits, Executor>(
0204       timer, timeout, cancel_type);
0205 }
0206
0207 /// Adapt a @ref completion_token to cancel an operation if not complete before
0208 /// the specified relative timeout has elapsed.
0209 /**
0210  * @par Thread Safety
0211  * When an asynchronous operation is used with cancel_after, a timer async_wait
0212  * operation is performed in parallel to the main operation. If this parallel
0213  * async_wait completes first, a cancellation request is emitted to cancel the
0214  * main operation. Consequently, the application must ensure that the
0215  * asynchronous operation is performed within an implicit or explicit strand.
0216  */
0217 template <typename Rep, typename Period, typename CompletionToken>
0218 BOOST_ASIO_NODISCARD inline
0219 cancel_after_t<decay_t<CompletionToken>, chrono::steady_clock>
0220 cancel_after(const chrono::duration<Rep, Period>& timeout,
0221     CompletionToken&& completion_token)
0222 {
0223   return cancel_after_t<decay_t<CompletionToken>, chrono::steady_clock>(
0224       static_cast<CompletionToken&&>(completion_token),
0225       timeout, cancellation_type::terminal);
0226 }
0227
0228 /// Adapt a @ref completion_token to cancel an operation if not complete before
0229 /// the specified relative timeout has elapsed.
0230 /**
0231  * @par Thread Safety
0232  * When an asynchronous operation is used with cancel_after, a timer async_wait
0233  * operation is performed in parallel to the main operation. If this parallel
0234  * async_wait completes first, a cancellation request is emitted to cancel the
0235  * main operation. Consequently, the application must ensure that the
0236  * asynchronous operation is performed within an implicit or explicit strand.
0237  */
0238 template <typename Rep, typename Period, typename CompletionToken>
0239 BOOST_ASIO_NODISCARD inline
0240 cancel_after_t<decay_t<CompletionToken>, chrono::steady_clock>
0241 cancel_after(const chrono::duration<Rep, Period>& timeout,
0242     cancellation_type_t cancel_type, CompletionToken&& completion_token)
0243 {
0244   return cancel_after_t<decay_t<CompletionToken>, chrono::steady_clock>(
0245       static_cast<CompletionToken&&>(completion_token), timeout, cancel_type);
0246 }
0247
0248 /// Adapt a @ref completion_token to cancel an operation if not complete before
0249 /// the specified relative timeout has elapsed.
0250 /**
0251  * @par Thread Safety
0252  * When an asynchronous operation is used with cancel_after, a timer async_wait
0253  * operation is performed in parallel to the main operation. If this parallel
0254  * async_wait completes first, a cancellation request is emitted to cancel the
0255  * main operation. Consequently, the application must ensure that the
0256  * asynchronous operation is performed within an implicit or explicit strand.
0257  */
0258 template <typename Clock, typename WaitTraits, typename Executor,
0259     typename Rep, typename Period, typename CompletionToken>
0260 BOOST_ASIO_NODISCARD inline
0261 cancel_after_timer<decay_t<CompletionToken>, Clock, WaitTraits, Executor>
0262 cancel_after(basic_waitable_timer<Clock, WaitTraits, Executor>& timer,
0263     const chrono::duration<Rep, Period>& timeout,
0264     CompletionToken&& completion_token)
0265 {
0266   return cancel_after_timer<decay_t<CompletionToken>,
0267     Clock, WaitTraits, Executor>(
0268       static_cast<CompletionToken&&>(completion_token),
0269       timer, timeout, cancellation_type::terminal);
0270 }
0271
0272 /// Adapt a @ref completion_token to cancel an operation if not complete before
0273 /// the specified relative timeout has elapsed.
0274 /**
0275  * @par Thread Safety
0276  * When an asynchronous operation is used with cancel_after, a timer async_wait
0277  * operation is performed in parallel to the main operation. If this parallel
0278  * async_wait completes first, a cancellation request is emitted to cancel the
0279  * main operation. Consequently, the application must ensure that the
0280  * asynchronous operation is performed within an implicit or explicit strand.
0281  */
0282 template <typename Clock, typename WaitTraits, typename Executor,
0283     typename Rep, typename Period, typename CompletionToken>
0284 BOOST_ASIO_NODISCARD inline
0285 cancel_after_timer<decay_t<CompletionToken>, chrono::steady_clock>
0286 cancel_after(basic_waitable_timer<Clock, WaitTraits, Executor>& timer,
0287     const chrono::duration<Rep, Period>& timeout,
0288     cancellation_type_t cancel_type, CompletionToken&& completion_token)
0289 {
0290   return cancel_after_timer<decay_t<CompletionToken>,
0291     Clock, WaitTraits, Executor>(
0292       static_cast<CompletionToken&&>(completion_token),
0293       timer, timeout, cancel_type);
0294 }
0295
0296 } // namespace asio
0297 } // namespace boost
0298
0299 #include <boost/asio/detail/pop_options.hpp>
0300
0301 #include <boost/asio/impl/cancel_after.hpp>
0302
0303 #endif // BOOST_ASIO_CANCEL_AFTER_HPP