1// Smart pointer adaptors -*- C++ -*-
2
3// Copyright The GNU Toolchain Authors.
4//
5// This file is part of the GNU ISO C++ Library. This library is free
6// software; you can redistribute it and/or modify it under the
7// terms of the GNU General Public License as published by the
8// Free Software Foundation; either version 3, or (at your option)
9// any later version.
10
11// This library is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// Under Section 7 of GPL version 3, you are granted additional
17// permissions described in the GCC Runtime Library Exception, version
18// 3.1, as published by the Free Software Foundation.
19
20// You should have received a copy of the GNU General Public License and
21// a copy of the GCC Runtime Library Exception along with this program;
22// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23// <http://www.gnu.org/licenses/>.
24
25/** @file include/bits/out_ptr.h
26 * This is an internal header file, included by other library headers.
27 * Do not attempt to use it directly. @headername{memory}
28 */
29
30#ifndef _GLIBCXX_OUT_PTR_H
31#define _GLIBCXX_OUT_PTR_H 1
32
33#ifdef _GLIBCXX_SYSHDR
34#pragma GCC system_header
35#endif
36
37#include <bits/version.h>
38
39#ifdef __glibcxx_out_ptr // C++ >= 23
40
41#include <tuple>
42#include <bits/ptr_traits.h>
43
44namespace std _GLIBCXX_VISIBILITY(default)
45{
46_GLIBCXX_BEGIN_NAMESPACE_VERSION
47
48 /// Smart pointer adaptor for functions taking an output pointer parameter.
49 /**
50 * @tparam _Smart The type of pointer to adapt.
51 * @tparam _Pointer The type of pointer to convert to.
52 * @tparam _Args... Argument types used when resetting the smart pointer.
53 * @since C++23
54 * @headerfile <memory>
55 */
56 template<typename _Smart, typename _Pointer, typename... _Args>
57 class out_ptr_t
58 {
59#if _GLIBCXX_HOSTED
60 static_assert(!__is_shared_ptr<_Smart> || sizeof...(_Args) != 0,
61 "a deleter must be used when adapting std::shared_ptr "
62 "with std::out_ptr");
63#endif
64
65 public:
66 explicit
67 out_ptr_t(_Smart& __smart, _Args... __args)
68 : _M_impl{__smart, std::forward<_Args>(__args)...}
69 {
70 if constexpr (requires { _M_impl._M_out_init(); })
71 _M_impl._M_out_init();
72 }
73
74 out_ptr_t(const out_ptr_t&) = delete;
75
76 ~out_ptr_t() = default;
77
78 operator _Pointer*() const noexcept
79 { return _M_impl._M_get(); }
80
81 operator void**() const noexcept requires (!same_as<_Pointer, void*>)
82 {
83 static_assert(is_pointer_v<_Pointer>);
84 _Pointer* __p = *this;
85 return static_cast<void**>(static_cast<void*>(__p));
86 }
87
88 private:
89 // TODO: Move this to namespace scope? e.g. __detail::_Ptr_adapt_impl
90 template<typename, typename, typename...>
91 struct _Impl
92 {
93 // This constructor must not modify __s because out_ptr_t and
94 // inout_ptr_t want to do different things. After construction
95 // they call _M_out_init() or _M_inout_init() respectively.
96 _Impl(_Smart& __s, _Args&&... __args)
97 : _M_smart(__s), _M_args(std::forward<_Args>(__args)...)
98 { }
99
100 // Called by out_ptr_t to clear the smart pointer before using it.
101 void
102 _M_out_init()
103 {
104 // _GLIBCXX_RESOLVE_LIB_DEFECTS
105 // 3734. Inconsistency in inout_ptr and out_ptr for empty case
106 if constexpr (requires { _M_smart.reset(); })
107 _M_smart.reset();
108 else
109 _M_smart = _Smart();
110 }
111
112 // Called by inout_ptr_t to copy the smart pointer's value
113 // to the pointer that is returned from _M_get().
114 void
115 _M_inout_init()
116 { _M_ptr = _M_smart.release(); }
117
118 // The pointer value returned by operator Pointer*().
119 _Pointer*
120 _M_get() const
121 { return __builtin_addressof(const_cast<_Pointer&>(_M_ptr)); }
122
123 // Finalize the effects on the smart pointer.
124 ~_Impl() noexcept(false);
125
126 _Smart& _M_smart;
127 [[no_unique_address]] _Pointer _M_ptr{};
128 [[no_unique_address]] tuple<_Args...> _M_args;
129 };
130
131 // Partial specialization for raw pointers.
132 template<typename _Tp>
133 struct _Impl<_Tp*, _Tp*>
134 {
135 void
136 _M_out_init()
137 { _M_p = nullptr; }
138
139 void
140 _M_inout_init()
141 { }
142
143 _Tp**
144 _M_get() const
145 { return __builtin_addressof(const_cast<_Tp*&>(_M_p)); }
146
147 _Tp*& _M_p;
148 };
149
150 // Partial specialization for raw pointers, with conversion.
151 template<typename _Tp, typename _Ptr> requires (!is_same_v<_Ptr, _Tp*>)
152 struct _Impl<_Tp*, _Ptr>
153 {
154 explicit
155 _Impl(_Tp*& __p)
156 : _M_p(__p)
157 { }
158
159 void
160 _M_out_init()
161 { _M_p = nullptr; }
162
163 void
164 _M_inout_init()
165 { _M_ptr = _M_p; }
166
167 _Pointer*
168 _M_get() const
169 { return __builtin_addressof(const_cast<_Pointer&>(_M_ptr)); }
170
171 ~_Impl() { _M_p = static_cast<_Tp*>(_M_ptr); }
172
173 _Tp*& _M_p;
174 _Pointer _M_ptr{};
175 };
176
177 // Partial specialization for std::unique_ptr.
178 // This specialization gives direct access to the private member
179 // of the unique_ptr, avoiding the overhead of storing a separate
180 // pointer and then resetting the unique_ptr in the destructor.
181 // FIXME: constrain to only match the primary template,
182 // not program-defined specializations of unique_ptr.
183 template<typename _Tp, typename _Del>
184 struct _Impl<unique_ptr<_Tp, _Del>,
185 typename unique_ptr<_Tp, _Del>::pointer>
186 {
187 void
188 _M_out_init()
189 { _M_smart.reset(); }
190
191 _Pointer*
192 _M_get() const noexcept
193 { return __builtin_addressof(_M_smart._M_t._M_ptr()); }
194
195 _Smart& _M_smart;
196 };
197
198 // Partial specialization for std::unique_ptr with replacement deleter.
199 // FIXME: constrain to only match the primary template,
200 // not program-defined specializations of unique_ptr.
201 template<typename _Tp, typename _Del, typename _Del2>
202 struct _Impl<unique_ptr<_Tp, _Del>,
203 typename unique_ptr<_Tp, _Del>::pointer, _Del2>
204 {
205 void
206 _M_out_init()
207 { _M_smart.reset(); }
208
209 _Pointer*
210 _M_get() const noexcept
211 { return __builtin_addressof(_M_smart._M_t._M_ptr()); }
212
213 ~_Impl()
214 {
215 if (_M_smart.get())
216 _M_smart._M_t._M_deleter() = std::forward<_Del2>(_M_del);
217 }
218
219 _Smart& _M_smart;
220 [[no_unique_address]] _Del2 _M_del;
221 };
222
223#if _GLIBCXX_HOSTED
224 // Partial specialization for std::shared_ptr.
225 // This specialization gives direct access to the private member
226 // of the shared_ptr, avoiding the overhead of storing a separate
227 // pointer and then resetting the shared_ptr in the destructor.
228 // A new control block is allocated in the constructor, so that if
229 // allocation fails it doesn't throw an exception from the destructor.
230 template<typename _Tp, typename _Del, typename _Alloc>
231 requires (is_base_of_v<__shared_ptr<_Tp>, shared_ptr<_Tp>>)
232 struct _Impl<shared_ptr<_Tp>,
233 typename shared_ptr<_Tp>::element_type*, _Del, _Alloc>
234 {
235 _Impl(_Smart& __s, _Del __d, _Alloc __a = _Alloc())
236 : _M_smart(__s)
237 {
238 // We know shared_ptr cannot be used with inout_ptr_t
239 // so we can do all set up here, instead of in _M_out_init().
240 _M_smart.reset();
241
242 // Similar to the shared_ptr(Y*, D, A) constructor, except that if
243 // the allocation throws we do not need (or want) to call deleter.
244 typename _Scd::__allocator_type __a2(__a);
245 auto __mem = __a2.allocate(1);
246 ::new (__mem) _Scd(nullptr, std::forward<_Del>(__d),
247 std::forward<_Alloc>(__a));
248 _M_smart._M_refcount._M_pi = __mem;
249 }
250
251 _Pointer*
252 _M_get() const noexcept
253 { return __builtin_addressof(_M_smart._M_ptr); }
254
255 ~_Impl()
256 {
257 auto& __pi = _M_smart._M_refcount._M_pi;
258
259 if (_Sp __ptr = _M_smart.get())
260 static_cast<_Scd*>(__pi)->_M_impl._M_ptr = __ptr;
261 else // Destroy the control block manually without invoking deleter.
262 std::__exchange(__pi, nullptr)->_M_destroy();
263 }
264
265 _Smart& _M_smart;
266
267 using _Sp = typename _Smart::element_type*;
268 using _Scd = _Sp_counted_deleter<_Sp, decay_t<_Del>,
269 remove_cvref_t<_Alloc>,
270 __default_lock_policy>;
271 };
272
273 // Partial specialization for std::shared_ptr, without custom allocator.
274 template<typename _Tp, typename _Del>
275 requires (is_base_of_v<__shared_ptr<_Tp>, shared_ptr<_Tp>>)
276 struct _Impl<shared_ptr<_Tp>,
277 typename shared_ptr<_Tp>::element_type*, _Del>
278 : _Impl<_Smart, _Pointer, _Del, allocator<void>>
279 {
280 using _Impl<_Smart, _Pointer, _Del, allocator<void>>::_Impl;
281 };
282#endif
283
284 using _Impl_t = _Impl<_Smart, _Pointer, _Args...>;
285
286 _Impl_t _M_impl;
287
288 template<typename, typename, typename...> friend class inout_ptr_t;
289 };
290
291 /// Smart pointer adaptor for functions taking an inout pointer parameter.
292 /**
293 * @tparam _Smart The type of pointer to adapt.
294 * @tparam _Pointer The type of pointer to convert to.
295 * @tparam _Args... Argument types used when resetting the smart pointer.
296 * @since C++23
297 * @headerfile <memory>
298 */
299 template<typename _Smart, typename _Pointer, typename... _Args>
300 class inout_ptr_t
301 {
302#if _GLIBCXX_HOSTED
303 static_assert(!__is_shared_ptr<_Smart>,
304 "std::inout_ptr can not be used to wrap std::shared_ptr");
305#endif
306
307 public:
308 explicit
309 inout_ptr_t(_Smart& __smart, _Args... __args)
310 : _M_impl{__smart, std::forward<_Args>(__args)...}
311 {
312 if constexpr (requires { _M_impl._M_inout_init(); })
313 _M_impl._M_inout_init();
314 }
315
316 inout_ptr_t(const inout_ptr_t&) = delete;
317
318 ~inout_ptr_t() = default;
319
320 operator _Pointer*() const noexcept
321 { return _M_impl._M_get(); }
322
323 operator void**() const noexcept requires (!same_as<_Pointer, void*>)
324 {
325 static_assert(is_pointer_v<_Pointer>);
326 _Pointer* __p = *this;
327 return static_cast<void**>(static_cast<void*>(__p));
328 }
329
330 private:
331#if _GLIBCXX_HOSTED
332 // Avoid an invalid instantiation of out_ptr_t<shared_ptr<T>, ...>
333 using _Out_ptr_t
334 = __conditional_t<__is_shared_ptr<_Smart>,
335 out_ptr_t<void*, void*>,
336 out_ptr_t<_Smart, _Pointer, _Args...>>;
337#else
338 using _Out_ptr_t = out_ptr_t<_Smart, _Pointer, _Args...>;
339#endif
340 using _Impl_t = typename _Out_ptr_t::_Impl_t;
341 _Impl_t _M_impl;
342 };
343
344/// @cond undocumented
345namespace __detail
346{
347 // POINTER_OF metafunction
348 template<typename _Tp>
349 consteval auto
350 __pointer_of()
351 {
352 if constexpr (requires { typename _Tp::pointer; })
353 return type_identity<typename _Tp::pointer>{};
354 else if constexpr (requires { typename _Tp::element_type; })
355 return type_identity<typename _Tp::element_type*>{};
356 else
357 {
358 using _Traits = pointer_traits<_Tp>;
359 if constexpr (requires { typename _Traits::element_type; })
360 return type_identity<typename _Traits::element_type*>{};
361 }
362 // else POINTER_OF(S) is not a valid type, return void.
363 }
364
365 // POINTER_OF_OR metafunction
366 template<typename _Smart, typename _Ptr>
367 consteval auto
368 __pointer_of_or()
369 {
370 using _TypeId = decltype(__detail::__pointer_of<_Smart>());
371 if constexpr (is_void_v<_TypeId>)
372 return type_identity<_Ptr>{};
373 else
374 return _TypeId{};
375 }
376
377 // Returns Pointer if !is_void_v<Pointer>, otherwise POINTER_OF(Smart).
378 template<typename _Ptr, typename _Smart>
379 consteval auto
380 __choose_ptr()
381 {
382 if constexpr (!is_void_v<_Ptr>)
383 return type_identity<_Ptr>{};
384 else
385 return __detail::__pointer_of<_Smart>();
386 }
387
388 template<typename _Smart, typename _Sp, typename... _Args>
389 concept __resettable = requires (_Smart& __s) {
390 __s.reset(std::declval<_Sp>(), std::declval<_Args>()...);
391 };
392}
393/// @endcond
394
395 /// Adapt a smart pointer for functions taking an output pointer parameter.
396 /**
397 * @tparam _Pointer The type of pointer to convert to.
398 * @param __s The pointer that should take ownership of the result.
399 * @param __args... Arguments to use when resetting the smart pointer.
400 * @return A std::inout_ptr_t referring to `__s`.
401 * @since C++23
402 * @headerfile <memory>
403 */
404 template<typename _Pointer = void, typename _Smart, typename... _Args>
405 inline auto
406 out_ptr(_Smart& __s, _Args&&... __args)
407 {
408 using _TypeId = decltype(__detail::__choose_ptr<_Pointer, _Smart>());
409 static_assert(!is_void_v<_TypeId>, "first argument to std::out_ptr "
410 "must be a pointer-like type");
411
412 using _Ret = out_ptr_t<_Smart, typename _TypeId::type, _Args&&...>;
413 return _Ret(__s, std::forward<_Args>(__args)...);
414 }
415
416 /// Adapt a smart pointer for functions taking an inout pointer parameter.
417 /**
418 * @tparam _Pointer The type of pointer to convert to.
419 * @param __s The pointer that should take ownership of the result.
420 * @param __args... Arguments to use when resetting the smart pointer.
421 * @return A std::inout_ptr_t referring to `__s`.
422 * @since C++23
423 * @headerfile <memory>
424 */
425 template<typename _Pointer = void, typename _Smart, typename... _Args>
426 inline auto
427 inout_ptr(_Smart& __s, _Args&&... __args)
428 {
429 using _TypeId = decltype(__detail::__choose_ptr<_Pointer, _Smart>());
430 static_assert(!is_void_v<_TypeId>, "first argument to std::inout_ptr "
431 "must be a pointer-like type");
432
433 using _Ret = inout_ptr_t<_Smart, typename _TypeId::type, _Args&&...>;
434 return _Ret(__s, std::forward<_Args>(__args)...);
435 }
436
437 /// @cond undocumented
438 template<typename _Smart, typename _Pointer, typename... _Args>
439 template<typename _Smart2, typename _Pointer2, typename... _Args2>
440 inline
441 out_ptr_t<_Smart, _Pointer, _Args...>::
442 _Impl<_Smart2, _Pointer2, _Args2...>::~_Impl()
443 {
444 using _TypeId = decltype(__detail::__pointer_of_or<_Smart, _Pointer>());
445 using _Sp = typename _TypeId::type;
446
447 if (!_M_ptr)
448 return;
449
450 _Smart& __s = _M_smart;
451 _Pointer& __p = _M_ptr;
452
453 auto __reset = [&](auto&&... __args) {
454 if constexpr (__detail::__resettable<_Smart, _Sp, _Args...>)
455 __s.reset(static_cast<_Sp>(__p), std::forward<_Args>(__args)...);
456 else if constexpr (is_constructible_v<_Smart, _Sp, _Args...>)
457 __s = _Smart(static_cast<_Sp>(__p), std::forward<_Args>(__args)...);
458 else
459 static_assert(is_constructible_v<_Smart, _Sp, _Args...>);
460 };
461
462 if constexpr (sizeof...(_Args) >= 2)
463 std::apply(__reset, std::move(_M_args));
464 else if constexpr (sizeof...(_Args) == 1)
465 __reset(std::get<0>(std::move(_M_args)));
466 else
467 __reset();
468 }
469 /// @endcond
470
471_GLIBCXX_END_NAMESPACE_VERSION
472} // namespace
473
474#endif // __glibcxx_out_ptr
475#endif /* _GLIBCXX_OUT_PTR_H */
476