From efa9d8eef07e0abc9d073e004c95d2812d35f88a Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 2 May 2019 22:23:25 +0100 Subject: [PATCH] Improve smart pointer docs * include/bits/shared_ptr.h: Improve docs. * include/bits/shared_ptr_atomic.h: Likewise. * include/bits/unique_ptr.h: Likewise. Adjust whitespace. From-SVN: r270825 --- libstdc++-v3/ChangeLog | 4 +++ libstdc++-v3/include/bits/shared_ptr.h | 30 ++++++++++++++++-- libstdc++-v3/include/bits/shared_ptr_atomic.h | 6 ++++ libstdc++-v3/include/bits/unique_ptr.h | 31 ++++++++++++++----- 4 files changed, 60 insertions(+), 11 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 32d1be1616f..3fe61147d07 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,9 @@ 2019-05-02 Jonathan Wakely + * include/bits/shared_ptr.h: Improve docs. + * include/bits/shared_ptr_atomic.h: Likewise. + * include/bits/unique_ptr.h: Likewise. Adjust whitespace. + * include/bits/basic_string.h: Fix iterator/index confusion in Doxygen comments. * include/bits/range_access.h: Fix Doxygen warnings. diff --git a/libstdc++-v3/include/bits/shared_ptr.h b/libstdc++-v3/include/bits/shared_ptr.h index 2d53478f1f4..a38c1988973 100644 --- a/libstdc++-v3/include/bits/shared_ptr.h +++ b/libstdc++-v3/include/bits/shared_ptr.h @@ -82,6 +82,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } /// 20.7.2.2.10 shared_ptr get_deleter + /// @relates shared_ptr template inline _Del* get_deleter(const shared_ptr<_Tp>& __p) noexcept @@ -96,8 +97,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief A smart pointer with reference-counted copy semantics. * - * The object pointed to is deleted when the last shared_ptr pointing to - * it is destroyed or reset. + * A `shared_ptr` object is either empty or _owns_ a pointer passed + * to the constructor. Copies of a `shared_ptr` share ownership of + * the same pointer. When the last `shared_ptr` that owns the pointer + * is destroyed or reset, the owned pointer is freed (either by `delete` + * or by invoking a custom deleter that was passed to the constructor). + * + * A `shared_ptr` also stores another pointer, which is usually + * (but not always) the same pointer as it owns. The stored pointer + * can be retrieved by calling the `get()` member function. */ template class shared_ptr : public __shared_ptr<_Tp> @@ -370,6 +378,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION friend class weak_ptr<_Tp>; }; + /// @relates shared_ptr @{ + #if __cpp_deduction_guides >= 201606 template shared_ptr(weak_ptr<_Tp>) -> shared_ptr<_Tp>; @@ -480,12 +490,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return !(nullptr < __a); } // 20.7.2.2.8 shared_ptr specialized algorithms. + /// Swap overload for shared_ptr template inline void swap(shared_ptr<_Tp>& __a, shared_ptr<_Tp>& __b) noexcept { __a.swap(__b); } // 20.7.2.2.9 shared_ptr casts. + /// Convert type of `shared_ptr`, via `static_cast` template inline shared_ptr<_Tp> static_pointer_cast(const shared_ptr<_Up>& __r) noexcept @@ -494,6 +506,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return _Sp(__r, static_cast(__r.get())); } + /// Convert type of `shared_ptr`, via `const_cast` template inline shared_ptr<_Tp> const_pointer_cast(const shared_ptr<_Up>& __r) noexcept @@ -502,6 +515,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return _Sp(__r, const_cast(__r.get())); } + /// Convert type of `shared_ptr`, via `dynamic_cast` template inline shared_ptr<_Tp> dynamic_pointer_cast(const shared_ptr<_Up>& __r) noexcept @@ -512,7 +526,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return _Sp(); } -#if __cplusplus > 201402L +#if __cplusplus >= 201703L + /// Convert type of `shared_ptr`, via `reinterpret_cast` template inline shared_ptr<_Tp> reinterpret_pointer_cast(const shared_ptr<_Up>& __r) noexcept @@ -522,6 +537,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } #endif + // @} + /** * @brief A smart pointer with weak semantics. * @@ -601,6 +618,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // 20.7.2.3.6 weak_ptr specialized algorithms. + /// Swap overload for weak_ptr + /// @relates weak_ptr template inline void swap(weak_ptr<_Tp>& __a, weak_ptr<_Tp>& __b) noexcept @@ -617,12 +636,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { }; /// Partial specialization of owner_less for shared_ptr. + /// @relates shared_ptr template struct owner_less> : public _Sp_owner_less, weak_ptr<_Tp>> { }; /// Partial specialization of owner_less for weak_ptr. + /// @relates weak_ptr template struct owner_less> : public _Sp_owner_less, shared_ptr<_Tp>> @@ -683,6 +704,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION mutable weak_ptr<_Tp> _M_weak_this; }; + /// @relates unique_ptr @{ + /** * @brief Create an object that is owned by a shared_ptr. * @param __a An allocator. @@ -730,6 +753,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } }; + // @} relates shared_ptr // @} group pointer_abstractions #if __cplusplus >= 201703L diff --git a/libstdc++-v3/include/bits/shared_ptr_atomic.h b/libstdc++-v3/include/bits/shared_ptr_atomic.h index fb99eb55b14..93c575a79f2 100644 --- a/libstdc++-v3/include/bits/shared_ptr_atomic.h +++ b/libstdc++-v3/include/bits/shared_ptr_atomic.h @@ -40,6 +40,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @addtogroup pointer_abstractions * @{ */ + /// @relates shared_ptr @{ + + /// @cond undocumented struct _Sp_locker { @@ -60,6 +63,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif }; + /// @endcond + /** * @brief Report whether shared_ptr atomic operations are lock-free. * @param __p A non-null pointer to a shared_ptr object. @@ -322,6 +327,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } // @} + // @} relates shared_ptr // @} group pointer_abstractions _GLIBCXX_END_NAMESPACE_VERSION diff --git a/libstdc++-v3/include/bits/unique_ptr.h b/libstdc++-v3/include/bits/unique_ptr.h index 963e4eb7d44..549db875783 100644 --- a/libstdc++-v3/include/bits/unique_ptr.h +++ b/libstdc++-v3/include/bits/unique_ptr.h @@ -686,6 +686,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION unique_ptr& operator=(const unique_ptr&) = delete; }; + /// @relates unique_ptr @{ + template inline #if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11 @@ -754,14 +756,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template _GLIBCXX_NODISCARD inline bool operator<(const unique_ptr<_Tp, _Dp>& __x, nullptr_t) - { return std::less::pointer>()(__x.get(), - nullptr); } + { + return std::less::pointer>()(__x.get(), + nullptr); + } template _GLIBCXX_NODISCARD inline bool operator<(nullptr_t, const unique_ptr<_Tp, _Dp>& __x) - { return std::less::pointer>()(nullptr, - __x.get()); } + { + return std::less::pointer>()(nullptr, + __x.get()); + } template @@ -790,14 +796,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template _GLIBCXX_NODISCARD inline bool operator>(const unique_ptr<_Tp, _Dp>& __x, nullptr_t) - { return std::less::pointer>()(nullptr, - __x.get()); } + { + return std::less::pointer>()(nullptr, + __x.get()); + } template _GLIBCXX_NODISCARD inline bool operator>(nullptr_t, const unique_ptr<_Tp, _Dp>& __x) - { return std::less::pointer>()(__x.get(), - nullptr); } + { + return std::less::pointer>()(__x.get(), + nullptr); + } template @@ -834,6 +844,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #define __cpp_lib_make_unique 201304 + /// @cond undocumented + template struct _MakeUniq { typedef unique_ptr<_Tp> __single_object; }; @@ -846,6 +858,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION struct _MakeUniq<_Tp[_Bound]> { struct __invalid_type { }; }; + /// @endcond + /// std::make_unique for single objects template inline typename _MakeUniq<_Tp>::__single_object @@ -864,6 +878,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION make_unique(_Args&&...) = delete; #endif + // @} relates unique_ptr // @} group pointer_abstractions #if __cplusplus >= 201703L -- 2.30.2