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