boost/asio/cancellation_state.hpp

0001 //
0002 // cancellation_state.hpp
0003 // ~~~~~~~~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2023 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_CANCELLATION_STATE_HPP
0012 #define BOOST_ASIO_CANCELLATION_STATE_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 <cassert>
0020 #include <new>
0021 #include <utility>
0022 #include <boost/asio/cancellation_signal.hpp>
0023 #include <boost/asio/detail/cstddef.hpp>
0024
0025 #include <boost/asio/detail/push_options.hpp>
0026
0027 namespace boost {
0028 namespace asio {
0029
0030 /// A simple cancellation signal propagation filter.
0031 template <cancellation_type_t Mask>
0032 struct cancellation_filter
0033 {
0034   /// Returns <tt>type & Mask</tt>.
0035   cancellation_type_t operator()(
0036       cancellation_type_t type) const noexcept
0037   {
0038     return type & Mask;
0039   }
0040 };
0041
0042 /// A cancellation filter that disables cancellation.
0043 typedef cancellation_filter<cancellation_type::none>
0044   disable_cancellation;
0045
0046 /// A cancellation filter that enables terminal cancellation only.
0047 typedef cancellation_filter<cancellation_type::terminal>
0048   enable_terminal_cancellation;
0049
0050 #if defined(GENERATING_DOCUMENTATION)
0051
0052 /// A cancellation filter that enables terminal and partial cancellation.
0053 typedef cancellation_filter<
0054     cancellation_type::terminal | cancellation_type::partial>
0055   enable_partial_cancellation;
0056
0057 /// A cancellation filter that enables terminal, partial and total cancellation.
0058 typedef cancellation_filter<cancellation_type::terminal
0059     | cancellation_type::partial | cancellation_type::total>
0060   enable_total_cancellation;
0061
0062 #else // defined(GENERATING_DOCUMENTATION)
0063
0064 typedef cancellation_filter<
0065     static_cast<cancellation_type_t>(
0066       static_cast<unsigned int>(cancellation_type::terminal)
0067         | static_cast<unsigned int>(cancellation_type::partial))>
0068   enable_partial_cancellation;
0069
0070 typedef cancellation_filter<
0071     static_cast<cancellation_type_t>(
0072       static_cast<unsigned int>(cancellation_type::terminal)
0073         | static_cast<unsigned int>(cancellation_type::partial)
0074         | static_cast<unsigned int>(cancellation_type::total))>
0075   enable_total_cancellation;
0076
0077 #endif // defined(GENERATING_DOCUMENTATION)
0078
0079 /// A cancellation state is used for chaining signals and slots in compositions.
0080 class cancellation_state
0081 {
0082 public:
0083   /// Construct a disconnected cancellation state.
0084   constexpr cancellation_state() noexcept
0085     : impl_(0)
0086   {
0087   }
0088
0089   /// Construct and attach to a parent slot to create a new child slot.
0090   /**
0091    * Initialises the cancellation state so that it allows terminal cancellation
0092    * only. Equivalent to <tt>cancellation_state(slot,
0093    * enable_terminal_cancellation())</tt>.
0094    *
0095    * @param slot The parent cancellation slot to which the state will be
0096    * attached.
0097    */
0098   template <typename CancellationSlot>
0099   constexpr explicit cancellation_state(CancellationSlot slot)
0100     : impl_(slot.is_connected() ? &slot.template emplace<impl<>>() : 0)
0101   {
0102   }
0103
0104   /// Construct and attach to a parent slot to create a new child slot.
0105   /**
0106    * @param slot The parent cancellation slot to which the state will be
0107    * attached.
0108    *
0109    * @param filter A function object that is used to transform incoming
0110    * cancellation signals as they are received from the parent slot. This
0111    * function object must have the signature:
0112    * @code boost::asio::cancellation_type_t filter(
0113    *     boost::asio::cancellation_type_t); @endcode
0114    *
0115    * The library provides the following pre-defined cancellation filters:
0116    *
0117    * @li boost::asio::disable_cancellation
0118    * @li boost::asio::enable_terminal_cancellation
0119    * @li boost::asio::enable_partial_cancellation
0120    * @li boost::asio::enable_total_cancellation
0121    */
0122   template <typename CancellationSlot, typename Filter>
0123   constexpr cancellation_state(CancellationSlot slot, Filter filter)
0124     : impl_(slot.is_connected()
0125         ? &slot.template emplace<impl<Filter, Filter>>(filter, filter)
0126         : 0)
0127   {
0128   }
0129
0130   /// Construct and attach to a parent slot to create a new child slot.
0131   /**
0132    * @param slot The parent cancellation slot to which the state will be
0133    * attached.
0134    *
0135    * @param in_filter A function object that is used to transform incoming
0136    * cancellation signals as they are received from the parent slot. This
0137    * function object must have the signature:
0138    * @code boost::asio::cancellation_type_t in_filter(
0139    *     boost::asio::cancellation_type_t); @endcode
0140    *
0141    * @param out_filter A function object that is used to transform outcoming
0142    * cancellation signals as they are relayed to the child slot. This function
0143    * object must have the signature:
0144    * @code boost::asio::cancellation_type_t out_filter(
0145    *     boost::asio::cancellation_type_t); @endcode
0146    *
0147    * The library provides the following pre-defined cancellation filters:
0148    *
0149    * @li boost::asio::disable_cancellation
0150    * @li boost::asio::enable_terminal_cancellation
0151    * @li boost::asio::enable_partial_cancellation
0152    * @li boost::asio::enable_total_cancellation
0153    */
0154   template <typename CancellationSlot, typename InFilter, typename OutFilter>
0155   constexpr cancellation_state(CancellationSlot slot,
0156       InFilter in_filter, OutFilter out_filter)
0157     : impl_(slot.is_connected()
0158         ? &slot.template emplace<impl<InFilter, OutFilter>>(
0159             static_cast<InFilter&&>(in_filter),
0160             static_cast<OutFilter&&>(out_filter))
0161         : 0)
0162   {
0163   }
0164
0165   /// Returns the single child slot associated with the state.
0166   /**
0167    * This sub-slot is used with the operations that are being composed.
0168    */
0169   constexpr cancellation_slot slot() const noexcept
0170   {
0171     return impl_ ? impl_->signal_.slot() : cancellation_slot();
0172   }
0173
0174   /// Returns the cancellation types that have been triggered.
0175   cancellation_type_t cancelled() const noexcept
0176   {
0177     return impl_ ? impl_->cancelled_ : cancellation_type_t();
0178   }
0179
0180   /// Clears the specified cancellation types, if they have been triggered.
0181   void clear(cancellation_type_t mask = cancellation_type::all)
0182     noexcept
0183   {
0184     if (impl_)
0185       impl_->cancelled_ &= ~mask;
0186   }
0187
0188 private:
0189   struct impl_base
0190   {
0191     impl_base()
0192       : cancelled_()
0193     {
0194     }
0195
0196     cancellation_signal signal_;
0197     cancellation_type_t cancelled_;
0198   };
0199
0200   template <
0201       typename InFilter = enable_terminal_cancellation,
0202       typename OutFilter = InFilter>
0203   struct impl : impl_base
0204   {
0205     impl()
0206       : in_filter_(),
0207         out_filter_()
0208     {
0209     }
0210
0211     impl(InFilter in_filter, OutFilter out_filter)
0212       : in_filter_(static_cast<InFilter&&>(in_filter)),
0213         out_filter_(static_cast<OutFilter&&>(out_filter))
0214     {
0215     }
0216
0217     void operator()(cancellation_type_t in)
0218     {
0219       this->cancelled_ = in_filter_(in);
0220       cancellation_type_t out = out_filter_(this->cancelled_);
0221       if (out != cancellation_type::none)
0222         this->signal_.emit(out);
0223     }
0224
0225     InFilter in_filter_;
0226     OutFilter out_filter_;
0227   };
0228
0229   impl_base* impl_;
0230 };
0231
0232 } // namespace asio
0233 } // namespace boost
0234
0235 #include <boost/asio/detail/pop_options.hpp>
0236
0237 #endif // BOOST_ASIO_CANCELLATION_STATE_HPP