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

   1 //
   2 // Copyright (c) 2016-2017 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/allocator.hpp>
  14 #include <boost/beast/core/detail/config.hpp>
  15 #include <boost/beast/core/detail/type_traits.hpp>
  16 #include <type_traits>
  17 #include <utility>
  18
  19 namespace boost {
  20 namespace beast {
  21
  22 /** A smart pointer container with associated completion handler.
  23
  24     This is a smart pointer that retains unique ownership of an
  25     object through a pointer. Memory is managed using the allocator
  26     associated with a completion handler stored in the object. The
  27     managed object is destroyed and its memory deallocated when one
  28     of the following occurs:
  29
  30     @li The function @ref invoke is called.
  31
  32     @li The function @ref release_handler is called.
  33
  34     @li The container is destroyed.
  35
  36     Objects of this type are used in the implementation of composed
  37     operations with states that are expensive or impossible to move.
  38     This container manages that non-trivial state on behalf of the
  39     composed operation.
  40
  41     @par Thread Safety
  42     @e Distinct @e objects: Safe.@n
  43     @e Shared @e objects: Unsafe.
  44
  45     @tparam T The type of the owned object. Must be noexcept destructible.
  46
  47     @tparam Handler The type of the completion handler.
  48 */
  49 template<class T, class Handler>
  50 class handler_ptr
  51 {
  52     using handler_storage_t = typename detail::aligned_union<1, Handler>::type;
  53
  54     T* t_ = nullptr;
  55     handler_storage_t h_;
  56
  57     void clear();
  58
  59 public:
  60     static_assert(std::is_nothrow_destructible<T>::value,
  61         "T must be nothrow destructible");
  62
  63     /// The type of element stored
  64     using element_type = T;
  65
  66     /// The type of handler stored
  67     using handler_type = Handler;
  68
  69     /// Default constructor (deleted).
  70     handler_ptr() = delete;
  71
  72     /// Copy assignment (deleted).
  73     handler_ptr& operator=(handler_ptr const&) = delete;
  74
  75     /// Move assignment (deleted).
  76     handler_ptr& operator=(handler_ptr &&) = delete;
  77
  78     /** Destructor
  79
  80         If `*this` owns an object the object is destroyed and
  81         the memory deallocated using the allocator associated
  82         with the handler.
  83     */
  84     ~handler_ptr();
  85
  86     /** Move constructor.
  87
  88         When this call returns, the moved-from container
  89         will have no owned object.
  90     */
  91     handler_ptr(handler_ptr&& other);
  92
  93     /// Copy constructor (deleted).
  94     handler_ptr(handler_ptr const& other) = delete;
  95
  96     /** Constructor
  97
  98         This creates a new container with an owned object of
  99         type `T`. The allocator associated with the handler will
 100         be used to allocate memory for the owned object. The
 101         constructor for the owned object will be called with the
 102         following equivalent signature:
 103
 104         @code
 105             T::T(Handler const&, Args&&...)
 106         @endcode
 107
 108         @par Exception Safety
 109         Strong guarantee.
 110
 111         @param handler The handler to associate with the owned
 112         object. The argument will be moved if it is an xvalue.
 113
 114         @param args Optional arguments forwarded to
 115         the owned object's constructor.
 116     */
 117     template<class DeducedHandler, class... Args>
 118     explicit handler_ptr(DeducedHandler&& handler, Args&&... args);
 119
 120     /// Returns a const reference to the handler
 121     handler_type const&
 122     handler() const
 123     {
 124         return *reinterpret_cast<Handler const*>(&h_);
 125     }
 126
 127     /// Returns a reference to the handler
 128     handler_type&
 129     handler()
 130     {
 131         return *reinterpret_cast<Handler*>(&h_);
 132     }
 133
 134     /** Returns a pointer to the owned object.
 135     */
 136     T*
 137     get() const
 138     {
 139         return t_;
 140     }
 141
 142     /// Return a reference to the owned object.
 143     T&
 144     operator*() const
 145     {
 146         return *t_;
 147     }
 148
 149     /// Return a pointer to the owned object.
 150     T*
 151     operator->() const
 152     {
 153         return t_;
 154     }
 155
 156     /** Release ownership of the handler
 157
 158         Requires: `*this` owns an object
 159
 160         Before this function returns, the owned object is
 161         destroyed, satisfying the deallocation-before-invocation
 162         Asio guarantee.
 163
 164         @return The released handler.
 165     */
 166     handler_type
 167     release_handler();
 168
 169     /** Invoke the handler in the owned object.
 170
 171         This function invokes the handler in the owned object
 172         with a forwarded argument list. Before the invocation,
 173         the owned object is destroyed, satisfying the
 174         deallocation-before-invocation Asio guarantee.
 175
 176         @note Care must be taken when the arguments are themselves
 177         stored in the owned object. Such arguments must first be
 178         moved to the stack or elsewhere, and then passed, or else
 179         undefined behavior will result.
 180     */
 181     template<class... Args>
 182     void
 183     invoke(Args&&... args);
 184 };
 185
 186 } // beast
 187 } // boost
 188
 189 #include <boost/beast/core/impl/handler_ptr.ipp>
 190
 191 #endif