ceph/src/boost/boost/beast/core/handler_ptr.hpp

   1 //
   2 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
   3 //
   4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 //
   7 // Official repository: https://github.com/boostorg/beast
   8 //
   9
  10 #ifndef BOOST_BEAST_HANDLER_PTR_HPP
  11 #define BOOST_BEAST_HANDLER_PTR_HPP
  12
  13 #include <boost/beast/core/detail/config.hpp>
  14 #include <boost/beast/core/detail/allocator.hpp>
  15 #include <boost/assert.hpp>
  16 #include <boost/config/pragma_message.hpp>
  17 #include <type_traits>
  18 #include <utility>
  19
  20 #ifndef BOOST_BEAST_DOXYGEN
  21
  22 BOOST_PRAGMA_MESSAGE("<boost/beast/core/handler_ptr.hpp> is DEPRECATED and will be removed in a future release.")
  23
  24 namespace boost {
  25 namespace beast {
  26
  27 /** A smart pointer container with associated completion handler.
  28
  29     This is a smart pointer that retains unique ownership of an
  30     object through a pointer. Memory is managed using the allocator
  31     associated with a completion handler stored in the object. The
  32     managed object is destroyed and its memory deallocated when one
  33     of the following occurs:
  34
  35     @li The function @ref invoke is called.
  36
  37     @li The function @ref release_handler is called.
  38
  39     @li The container is destroyed.
  40
  41     Objects of this type are used in the implementation of composed
  42     operations with states that are expensive or impossible to move.
  43     This container manages that non-trivial state on behalf of the
  44     composed operation.
  45
  46     @par Thread Safety
  47     @e Distinct @e objects: Safe.@n
  48     @e Shared @e objects: Unsafe.
  49
  50     @tparam T The type of the owned object. Must be noexcept destructible.
  51
  52     @tparam Handler The type of the completion handler.
  53 */
  54 template<class T, class Handler>
  55 class handler_ptr
  56 {
  57 #ifndef BOOST_BEAST_ALLOW_DEPRECATED
  58     static_assert(sizeof(T) == 0,
  59         BOOST_BEAST_DEPRECATION_STRING);
  60 #endif
  61
  62     T* t_ = nullptr;
  63     union
  64     {
  65         Handler h_;
  66     };
  67
  68     void clear();
  69
  70 public:
  71     /// The type of element stored
  72     using element_type = T;
  73
  74     /// The type of handler stored
  75     using handler_type = Handler;
  76
  77     /// Default constructor (deleted).
  78     handler_ptr() = delete;
  79
  80     /// Copy assignment (deleted).
  81     handler_ptr& operator=(handler_ptr const&) = delete;
  82
  83     /// Move assignment (deleted).
  84     handler_ptr& operator=(handler_ptr &&) = delete;
  85
  86     /** Destructor
  87
  88         If `*this` owns an object the object is destroyed and
  89         the memory deallocated using the allocator associated
  90         with the handler.
  91     */
  92     ~handler_ptr();
  93
  94     /** Move constructor.
  95
  96         When this call returns, the moved-from container
  97         will have no owned object.
  98     */
  99     handler_ptr(handler_ptr&& other);
 100
 101     /// Copy constructor (deleted).
 102     handler_ptr(handler_ptr const& other) = delete;
 103
 104     /** Constructor
 105
 106         This creates a new container with an owned object of
 107         type `T`. The allocator associated with the handler will
 108         be used to allocate memory for the owned object. The
 109         constructor for the owned object will be called with the
 110         following equivalent signature:
 111
 112         @code
 113             T::T(Handler const&, Args&&...)
 114         @endcode
 115
 116         @esafe
 117         Strong guarantee.
 118
 119         @param handler The handler to associate with the owned object.
 120         The implementation takes ownership of the handler by performing a decay-copy.
 121
 122         @param args Optional arguments forwarded to
 123         the owned object's constructor.
 124     */
 125     template<class DeducedHandler, class... Args>
 126     explicit
 127     handler_ptr(DeducedHandler&& handler, Args&&... args);
 128
 129     /// Return a reference to the handler
 130     handler_type const&
 131     handler() const noexcept
 132     {
 133         return h_;
 134     }
 135
 136     /// Return a reference to the handler
 137     handler_type&
 138     handler() noexcept
 139     {
 140         return h_;
 141     }
 142
 143     /// Return `true` if `*this` owns an object
 144     bool
 145     has_value() const noexcept
 146     {
 147         return t_ != nullptr;
 148     }
 149
 150     /** Return a pointer to the owned object.
 151
 152         @par Preconditions:
 153         `has_value() == true`
 154     */
 155     T*
 156     get() const
 157     {
 158         BOOST_ASSERT(t_);
 159         return t_;
 160     }
 161
 162     /** Return a reference to the owned object.
 163
 164         @par Preconditions:
 165         `has_value() == true`
 166     */
 167     T&
 168     operator*() const
 169     {
 170         BOOST_ASSERT(t_);
 171         return *t_;
 172     }
 173
 174     /// Return a pointer to the owned object.
 175     T*
 176     operator->() const
 177     {
 178         BOOST_ASSERT(t_);
 179         return t_;
 180     }
 181
 182     /** Returns ownership of the handler
 183
 184         Before this function returns, the owned object is
 185         destroyed, satisfying the deallocation-before-invocation
 186         Asio guarantee.
 187
 188         @return The released handler.
 189
 190         @par Preconditions:
 191         `has_value() == true`
 192
 193         @par Postconditions:
 194         `has_value() == false`
 195     */
 196     handler_type
 197     release_handler();
 198
 199     /** Invoke the handler in the owned object.
 200
 201         This function invokes the handler in the owned object
 202         with a forwarded argument list. Before the invocation,
 203         the owned object is destroyed, satisfying the
 204         deallocation-before-invocation Asio guarantee.
 205
 206         @par Preconditions:
 207         `has_value() == true`
 208
 209         @par Postconditions:
 210         `has_value() == false`
 211
 212         @note Care must be taken when the arguments are themselves
 213         stored in the owned object. Such arguments must first be
 214         moved to the stack or elsewhere, and then passed, or else
 215         undefined behavior will result.
 216     */
 217     template<class... Args>
 218     void
 219     invoke(Args&&... args);
 220 };
 221
 222 } // beast
 223 } // boost
 224
 225 #include <boost/beast/core/impl/handler_ptr.hpp>
 226
 227 #endif
 228
 229 #endif