]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // |
92f5a8d4 | 2 | // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) |
7c673cae FG |
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 | // | |
b32b8144 FG |
7 | // Official repository: https://github.com/boostorg/beast |
8 | // | |
7c673cae | 9 | |
b32b8144 FG |
10 | #ifndef BOOST_BEAST_HANDLER_PTR_HPP |
11 | #define BOOST_BEAST_HANDLER_PTR_HPP | |
7c673cae | 12 | |
b32b8144 | 13 | #include <boost/beast/core/detail/config.hpp> |
92f5a8d4 TL |
14 | #include <boost/beast/core/detail/allocator.hpp> |
15 | #include <boost/assert.hpp> | |
16 | #include <boost/config/pragma_message.hpp> | |
7c673cae FG |
17 | #include <type_traits> |
18 | #include <utility> | |
19 | ||
92f5a8d4 TL |
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 | ||
b32b8144 | 24 | namespace boost { |
7c673cae FG |
25 | namespace beast { |
26 | ||
27 | /** A smart pointer container with associated completion handler. | |
28 | ||
11fdf7f2 TL |
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: | |
7c673cae FG |
34 | |
35 | @li The function @ref invoke is called. | |
36 | ||
37 | @li The function @ref release_handler is called. | |
38 | ||
11fdf7f2 | 39 | @li The container is destroyed. |
7c673cae | 40 | |
11fdf7f2 TL |
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. | |
7c673cae | 45 | |
11fdf7f2 TL |
46 | @par Thread Safety |
47 | @e Distinct @e objects: Safe.@n | |
48 | @e Shared @e objects: Unsafe. | |
7c673cae | 49 | |
11fdf7f2 | 50 | @tparam T The type of the owned object. Must be noexcept destructible. |
7c673cae FG |
51 | |
52 | @tparam Handler The type of the completion handler. | |
53 | */ | |
54 | template<class T, class Handler> | |
55 | class handler_ptr | |
56 | { | |
92f5a8d4 TL |
57 | #ifndef BOOST_BEAST_ALLOW_DEPRECATED |
58 | static_assert(sizeof(T) == 0, | |
59 | BOOST_BEAST_DEPRECATION_STRING); | |
60 | #endif | |
7c673cae | 61 | |
11fdf7f2 | 62 | T* t_ = nullptr; |
92f5a8d4 TL |
63 | union |
64 | { | |
65 | Handler h_; | |
66 | }; | |
7c673cae | 67 | |
11fdf7f2 | 68 | void clear(); |
7c673cae FG |
69 | |
70 | public: | |
11fdf7f2 | 71 | /// The type of element stored |
7c673cae FG |
72 | using element_type = T; |
73 | ||
11fdf7f2 | 74 | /// The type of handler stored |
7c673cae FG |
75 | using handler_type = Handler; |
76 | ||
11fdf7f2 TL |
77 | /// Default constructor (deleted). |
78 | handler_ptr() = delete; | |
79 | ||
80 | /// Copy assignment (deleted). | |
7c673cae FG |
81 | handler_ptr& operator=(handler_ptr const&) = delete; |
82 | ||
11fdf7f2 TL |
83 | /// Move assignment (deleted). |
84 | handler_ptr& operator=(handler_ptr &&) = delete; | |
85 | ||
86 | /** Destructor | |
7c673cae | 87 | |
11fdf7f2 TL |
88 | If `*this` owns an object the object is destroyed and |
89 | the memory deallocated using the allocator associated | |
90 | with the handler. | |
7c673cae FG |
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 | ||
11fdf7f2 TL |
101 | /// Copy constructor (deleted). |
102 | handler_ptr(handler_ptr const& other) = delete; | |
7c673cae | 103 | |
11fdf7f2 | 104 | /** Constructor |
7c673cae | 105 | |
11fdf7f2 TL |
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: | |
7c673cae FG |
111 | |
112 | @code | |
11fdf7f2 | 113 | T::T(Handler const&, Args&&...) |
7c673cae FG |
114 | @endcode |
115 | ||
92f5a8d4 | 116 | @esafe |
11fdf7f2 | 117 | Strong guarantee. |
7c673cae | 118 | |
92f5a8d4 TL |
119 | @param handler The handler to associate with the owned object. |
120 | The implementation takes ownership of the handler by performing a decay-copy. | |
7c673cae FG |
121 | |
122 | @param args Optional arguments forwarded to | |
123 | the owned object's constructor. | |
124 | */ | |
11fdf7f2 | 125 | template<class DeducedHandler, class... Args> |
92f5a8d4 TL |
126 | explicit |
127 | handler_ptr(DeducedHandler&& handler, Args&&... args); | |
7c673cae | 128 | |
92f5a8d4 | 129 | /// Return a reference to the handler |
11fdf7f2 | 130 | handler_type const& |
92f5a8d4 | 131 | handler() const noexcept |
7c673cae | 132 | { |
92f5a8d4 | 133 | return h_; |
7c673cae FG |
134 | } |
135 | ||
92f5a8d4 | 136 | /// Return a reference to the handler |
11fdf7f2 | 137 | handler_type& |
92f5a8d4 TL |
138 | handler() noexcept |
139 | { | |
140 | return h_; | |
141 | } | |
142 | ||
143 | /// Return `true` if `*this` owns an object | |
144 | bool | |
145 | has_value() const noexcept | |
7c673cae | 146 | { |
92f5a8d4 | 147 | return t_ != nullptr; |
7c673cae FG |
148 | } |
149 | ||
92f5a8d4 TL |
150 | /** Return a pointer to the owned object. |
151 | ||
152 | @par Preconditions: | |
153 | `has_value() == true` | |
7c673cae FG |
154 | */ |
155 | T* | |
156 | get() const | |
157 | { | |
92f5a8d4 | 158 | BOOST_ASSERT(t_); |
11fdf7f2 | 159 | return t_; |
7c673cae FG |
160 | } |
161 | ||
92f5a8d4 TL |
162 | /** Return a reference to the owned object. |
163 | ||
164 | @par Preconditions: | |
165 | `has_value() == true` | |
166 | */ | |
7c673cae FG |
167 | T& |
168 | operator*() const | |
169 | { | |
92f5a8d4 | 170 | BOOST_ASSERT(t_); |
11fdf7f2 | 171 | return *t_; |
7c673cae FG |
172 | } |
173 | ||
174 | /// Return a pointer to the owned object. | |
175 | T* | |
176 | operator->() const | |
177 | { | |
92f5a8d4 | 178 | BOOST_ASSERT(t_); |
11fdf7f2 | 179 | return t_; |
7c673cae FG |
180 | } |
181 | ||
92f5a8d4 | 182 | /** Returns ownership of the handler |
11fdf7f2 TL |
183 | |
184 | Before this function returns, the owned object is | |
185 | destroyed, satisfying the deallocation-before-invocation | |
186 | Asio guarantee. | |
7c673cae FG |
187 | |
188 | @return The released handler. | |
92f5a8d4 TL |
189 | |
190 | @par Preconditions: | |
191 | `has_value() == true` | |
192 | ||
193 | @par Postconditions: | |
194 | `has_value() == false` | |
7c673cae FG |
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 | |
11fdf7f2 | 204 | deallocation-before-invocation Asio guarantee. |
b32b8144 | 205 | |
92f5a8d4 TL |
206 | @par Preconditions: |
207 | `has_value() == true` | |
208 | ||
209 | @par Postconditions: | |
210 | `has_value() == false` | |
211 | ||
b32b8144 FG |
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. | |
7c673cae FG |
216 | */ |
217 | template<class... Args> | |
218 | void | |
219 | invoke(Args&&... args); | |
220 | }; | |
221 | ||
222 | } // beast | |
b32b8144 | 223 | } // boost |
7c673cae | 224 | |
92f5a8d4 TL |
225 | #include <boost/beast/core/impl/handler_ptr.hpp> |
226 | ||
227 | #endif | |
7c673cae FG |
228 | |
229 | #endif |