boost/asio/cancel_at.hpp

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