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
This commit is contained in:
Jonathan Wakely
Jonathan Wakely
parent
c4cb56a154
commit
efa9d8eef0
4 changed files with 60 additions and 11 deletions
|
|
@ -1,5 +1,9 @@
|
|||
2019-05-02 Jonathan Wakely <jwakely@redhat.com>
|
||||
|
||||
* 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.
|
||||
|
|
|
|||
|
|
@ -82,6 +82,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
}
|
||||
|
||||
/// 20.7.2.2.10 shared_ptr get_deleter
|
||||
/// @relates shared_ptr
|
||||
template<typename _Del, typename _Tp>
|
||||
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<typename _Tp>
|
||||
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<typename _Tp>
|
||||
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<typename _Tp>
|
||||
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<typename _Tp, typename _Up>
|
||||
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<typename _Sp::element_type*>(__r.get()));
|
||||
}
|
||||
|
||||
/// Convert type of `shared_ptr`, via `const_cast`
|
||||
template<typename _Tp, typename _Up>
|
||||
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<typename _Sp::element_type*>(__r.get()));
|
||||
}
|
||||
|
||||
/// Convert type of `shared_ptr`, via `dynamic_cast`
|
||||
template<typename _Tp, typename _Up>
|
||||
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<typename _Tp, typename _Up>
|
||||
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<typename _Tp>
|
||||
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<typename _Tp>
|
||||
struct owner_less<shared_ptr<_Tp>>
|
||||
: public _Sp_owner_less<shared_ptr<_Tp>, weak_ptr<_Tp>>
|
||||
{ };
|
||||
|
||||
/// Partial specialization of owner_less for weak_ptr.
|
||||
/// @relates weak_ptr
|
||||
template<typename _Tp>
|
||||
struct owner_less<weak_ptr<_Tp>>
|
||||
: public _Sp_owner_less<weak_ptr<_Tp>, 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -686,6 +686,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
unique_ptr& operator=(const unique_ptr&) = delete;
|
||||
};
|
||||
|
||||
/// @relates unique_ptr @{
|
||||
|
||||
template<typename _Tp, typename _Dp>
|
||||
inline
|
||||
#if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11
|
||||
|
|
@ -754,14 +756,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
template<typename _Tp, typename _Dp>
|
||||
_GLIBCXX_NODISCARD inline bool
|
||||
operator<(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
|
||||
{ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
|
||||
nullptr); }
|
||||
{
|
||||
return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
|
||||
nullptr);
|
||||
}
|
||||
|
||||
template<typename _Tp, typename _Dp>
|
||||
_GLIBCXX_NODISCARD inline bool
|
||||
operator<(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
|
||||
{ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
|
||||
__x.get()); }
|
||||
{
|
||||
return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
|
||||
__x.get());
|
||||
}
|
||||
|
||||
template<typename _Tp, typename _Dp,
|
||||
typename _Up, typename _Ep>
|
||||
|
|
@ -790,14 +796,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
template<typename _Tp, typename _Dp>
|
||||
_GLIBCXX_NODISCARD inline bool
|
||||
operator>(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
|
||||
{ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
|
||||
__x.get()); }
|
||||
{
|
||||
return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
|
||||
__x.get());
|
||||
}
|
||||
|
||||
template<typename _Tp, typename _Dp>
|
||||
_GLIBCXX_NODISCARD inline bool
|
||||
operator>(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
|
||||
{ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
|
||||
nullptr); }
|
||||
{
|
||||
return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
|
||||
nullptr);
|
||||
}
|
||||
|
||||
template<typename _Tp, typename _Dp,
|
||||
typename _Up, typename _Ep>
|
||||
|
|
@ -834,6 +844,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
|
||||
#define __cpp_lib_make_unique 201304
|
||||
|
||||
/// @cond undocumented
|
||||
|
||||
template<typename _Tp>
|
||||
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<typename _Tp, typename... _Args>
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue