* include/bits/shared_ptr.h: Improve docs.
* include/bits/shared_ptr_base.h: Likewise.
* include/bits/stl_uninitialized.h: Likewise.
* include/bits/unique_ptr.h: Likewise.
* libsupc++/new: Likewise.
From-SVN: r271077
+2019-05-10 Jonathan Wakely <jwakely@redhat.com>
+
+ * include/bits/shared_ptr.h: Improve docs.
+ * include/bits/shared_ptr_base.h: Likewise.
+ * include/bits/stl_uninitialized.h: Likewise.
+ * include/bits/unique_ptr.h: Likewise.
+ * libsupc++/new: Likewise.
+
2019-05-09 François Dumont <fdumont@gcc.gnu.org>
* include/bits/stl_deque.h
* @{
*/
- /// 20.7.2.2.11 shared_ptr I/O
+ // 20.7.2.2.11 shared_ptr I/O
+
+ /// Write the stored pointer to an ostream.
+ /// @relates shared_ptr
template<typename _Ch, typename _Tr, typename _Tp, _Lock_policy _Lp>
inline std::basic_ostream<_Ch, _Tr>&
operator<<(std::basic_ostream<_Ch, _Tr>& __os,
}
/// 20.7.2.2.10 shared_ptr get_deleter
+
+ /// If `__p` has a deleter of type `_Del`, return a pointer to it.
/// @relates shared_ptr
template<typename _Del, typename _Tp>
inline _Del*
* 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.
+ *
+ * The equality and relational operators for `shared_ptr` only compare
+ * the stored pointer returned by `get()`, not the owned pointer.
+ * To test whether two `shared_ptr` objects share ownership of the same
+ * pointer see `std::shared_ptr::owner_before` and `std::owner_less`.
*/
template<typename _Tp>
class shared_ptr : public __shared_ptr<_Tp>
public:
+ /// The type pointed to by the stored pointer, remove_extent_t<_Tp>
using element_type = typename __shared_ptr<_Tp>::element_type;
-#if __cplusplus > 201402L
+#if __cplusplus >= 201703L
# define __cpp_lib_shared_ptr_weak_type 201606
+ /// The corresponding weak_ptr type for this shared_ptr
using weak_type = weak_ptr<_Tp>;
#endif
/**
*/
constexpr shared_ptr() noexcept : __shared_ptr<_Tp>() { }
- shared_ptr(const shared_ptr&) noexcept = default;
+ shared_ptr(const shared_ptr&) noexcept = default; ///< Copy constructor
/**
* @brief Construct a %shared_ptr that owns the pointer @a __p.
friend class weak_ptr<_Tp>;
};
- /// @relates shared_ptr @{
-
#if __cpp_deduction_guides >= 201606
template<typename _Tp>
shared_ptr(weak_ptr<_Tp>) -> shared_ptr<_Tp>;
#endif
// 20.7.2.2.7 shared_ptr comparisons
+
+ /// @relates shared_ptr @{
+
+ /// Equality operator for shared_ptr objects, compares the stored pointers
template<typename _Tp, typename _Up>
_GLIBCXX_NODISCARD inline bool
operator==(const shared_ptr<_Tp>& __a, const shared_ptr<_Up>& __b) noexcept
{ return __a.get() == __b.get(); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator==(const shared_ptr<_Tp>& __a, nullptr_t) noexcept
{ return !__a; }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator==(nullptr_t, const shared_ptr<_Tp>& __a) noexcept
{ return !__a; }
+ /// Inequality operator for shared_ptr objects, compares the stored pointers
template<typename _Tp, typename _Up>
_GLIBCXX_NODISCARD inline bool
operator!=(const shared_ptr<_Tp>& __a, const shared_ptr<_Up>& __b) noexcept
{ return __a.get() != __b.get(); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator!=(const shared_ptr<_Tp>& __a, nullptr_t) noexcept
{ return (bool)__a; }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator!=(nullptr_t, const shared_ptr<_Tp>& __a) noexcept
{ return (bool)__a; }
+ /// Relational operator for shared_ptr objects, compares the stored pointers
template<typename _Tp, typename _Up>
_GLIBCXX_NODISCARD inline bool
operator<(const shared_ptr<_Tp>& __a, const shared_ptr<_Up>& __b) noexcept
return less<_Vp>()(__a.get(), __b.get());
}
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator<(const shared_ptr<_Tp>& __a, nullptr_t) noexcept
return less<_Tp_elt*>()(__a.get(), nullptr);
}
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator<(nullptr_t, const shared_ptr<_Tp>& __a) noexcept
return less<_Tp_elt*>()(nullptr, __a.get());
}
+ /// Relational operator for shared_ptr objects, compares the stored pointers
template<typename _Tp, typename _Up>
_GLIBCXX_NODISCARD inline bool
operator<=(const shared_ptr<_Tp>& __a, const shared_ptr<_Up>& __b) noexcept
{ return !(__b < __a); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator<=(const shared_ptr<_Tp>& __a, nullptr_t) noexcept
{ return !(nullptr < __a); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator<=(nullptr_t, const shared_ptr<_Tp>& __a) noexcept
{ return !(__a < nullptr); }
+ /// Relational operator for shared_ptr objects, compares the stored pointers
template<typename _Tp, typename _Up>
_GLIBCXX_NODISCARD inline bool
operator>(const shared_ptr<_Tp>& __a, const shared_ptr<_Up>& __b) noexcept
{ return (__b < __a); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator>(const shared_ptr<_Tp>& __a, nullptr_t) noexcept
{ return nullptr < __a; }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator>(nullptr_t, const shared_ptr<_Tp>& __a) noexcept
{ return __a < nullptr; }
+ /// Relational operator for shared_ptr objects, compares the stored pointers
template<typename _Tp, typename _Up>
_GLIBCXX_NODISCARD inline bool
operator>=(const shared_ptr<_Tp>& __a, const shared_ptr<_Up>& __b) noexcept
{ return !(__a < __b); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator>=(const shared_ptr<_Tp>& __a, nullptr_t) noexcept
{ return !(__a < nullptr); }
+ /// shared_ptr comparison with nullptr
template<typename _Tp>
_GLIBCXX_NODISCARD inline bool
operator>=(nullptr_t, const shared_ptr<_Tp>& __a) noexcept
{ return !(nullptr < __a); }
// 20.7.2.2.8 shared_ptr specialized algorithms.
+
/// Swap overload for shared_ptr
template<typename _Tp>
inline void
{ __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>
// @}
/**
- * @brief A smart pointer with weak semantics.
+ * @brief A non-owning observer for a pointer owned by a shared_ptr
+ *
+ * A weak_ptr provides a safe alternative to a raw pointer when you want
+ * a non-owning reference to an object that is managed by a shared_ptr.
*
- * With forwarding constructors and assignment operators.
+ * Unlike a raw pointer, a weak_ptr can be converted to a new shared_ptr
+ * that shares ownership with every other shared_ptr that already owns
+ * the pointer. In other words you can upgrade from a non-owning "weak"
+ * reference to an owning shared_ptr, without having access to any of
+ * the existing shared_ptr objects.
+ *
+ * Also unlike a raw pointer, a weak_ptr does not become "dangling" after
+ * the object it points to has been destroyed. Instead, a weak_ptr
+ * becomes _expired_ and can no longer be converted to a shared_ptr that
+ * owns the freed pointer, so you cannot accidentally access the pointed-to
+ * object after it has been destroyed.
*/
template<typename _Tp>
class weak_ptr : public __weak_ptr<_Tp>
template<typename _Tp = void>
struct owner_less;
- /// Void specialization of owner_less
+ /// Void specialization of owner_less compares either shared_ptr or weak_ptr
template<>
struct owner_less<void> : _Sp_owner_less<void, void>
{ };
/// 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>>
mutable weak_ptr<_Tp> _M_weak_this;
};
- /// @relates unique_ptr @{
+ /// @relates shared_ptr @{
/**
* @brief Create an object that is owned by a shared_ptr.
reset(_Yp* __p, _Deleter __d, _Alloc __a)
{ __shared_ptr(__p, std::move(__d), std::move(__a)).swap(*this); }
+ /// Return the stored pointer.
element_type*
get() const noexcept
{ return _M_ptr; }
+ /// Return true if the stored pointer is not null.
explicit operator bool() const // never throws
{ return _M_ptr == 0 ? false : true; }
+ /// Return true if use_count() == 1.
bool
unique() const noexcept
{ return _M_refcount._M_unique(); }
+ /// If *this owns a pointer, return the number of owners, otherwise zero.
long
use_count() const noexcept
{ return _M_refcount._M_get_use_count(); }
+ /// Exchange both the owned pointer and the stored pointer.
void
swap(__shared_ptr<_Tp, _Lp>& __other) noexcept
{
_M_refcount._M_swap(__other._M_refcount);
}
+ /** @brief Define an ordering based on ownership.
+ *
+ * This function defines a strict weak ordering between two shared_ptr
+ * or weak_ptr objects, such that one object is less than the other
+ * unless they share ownership of the same pointer, or are both empty.
+ * @{
+ */
template<typename _Tp1>
bool
owner_before(__shared_ptr<_Tp1, _Lp> const& __rhs) const noexcept
bool
owner_before(__weak_ptr<_Tp1, _Lp> const& __rhs) const noexcept
{ return _M_refcount._M_less(__rhs._M_refcount); }
+ // @}
protected:
// This constructor is non-standard, it is used by allocate_shared.
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
+ /** @addtogroup memory
+ * @{
+ */
+
+ /// @cond undocumented
+
template<bool _TrivialValueTypes>
struct __uninitialized_copy
{
{ return std::copy(__first, __last, __result); }
};
+ /// @endcond
+
/**
* @brief Copies the range [first,last) into result.
* @param __first An input iterator.
__uninit_copy(__first, __last, __result);
}
+ /// @cond undocumented
template<bool _TrivialValueType>
struct __uninitialized_fill
{ std::fill(__first, __last, __x); }
};
+ /// @endcond
+
/**
* @brief Copies the value x into the range [first,last).
* @param __first An input iterator.
__uninit_fill(__first, __last, __x);
}
+ /// @cond undocumented
template<bool _TrivialValueType>
struct __uninitialized_fill_n
{ return std::fill_n(__first, __n, __x); }
};
+ /// @endcond
+
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// DR 1339. uninitialized_fill_n should return the end of its range
/**
__uninit_fill_n(__first, __n, __x);
}
+ /// @cond undocumented
+
// Extensions: versions of uninitialized_copy, uninitialized_fill,
// and uninitialized_fill_n that take an allocator parameter.
// We dispatch back to the standard versions when we're given the
}
}
+ /// @endcond
+
#if __cplusplus >= 201103L
+ /// @cond undocumented
+
// Extensions: __uninitialized_default, __uninitialized_default_n,
// __uninitialized_default_a, __uninitialized_default_n_a.
return {__first_res, __second_res};
}
+ /// @endcond
+
/**
* @brief Copies the range [first,first+n) into result.
* @param __first An input iterator.
{ return std::__uninitialized_copy_n(__first, __n, __result,
std::__iterator_category(__first)); }
+ /// @cond undocumented
template<typename _InputIterator, typename _Size, typename _ForwardIterator>
inline pair<_InputIterator, _ForwardIterator>
__uninitialized_copy_n_pair(_InputIterator __first, _Size __n,
std::__uninitialized_copy_n_pair(__first, __n, __result,
std::__iterator_category(__first));
}
-
+ /// @endcond
#endif
#if __cplusplus >= 201703L
# define __cpp_lib_raw_memory_algorithms 201606L
+ /**
+ * @brief Default-initializes objects in the range [first,last).
+ * @param __first A forward iterator.
+ * @param __last A forward iterator.
+ */
template <typename _ForwardIterator>
inline void
uninitialized_default_construct(_ForwardIterator __first,
__uninitialized_default_novalue(__first, __last);
}
+ /**
+ * @brief Default-initializes objects in the range [first,first+count).
+ * @param __first A forward iterator.
+ * @param __count The number of objects to construct.
+ * @return __first + __count
+ */
template <typename _ForwardIterator, typename _Size>
inline _ForwardIterator
uninitialized_default_construct_n(_ForwardIterator __first, _Size __count)
return __uninitialized_default_novalue_n(__first, __count);
}
+ /**
+ * @brief Value-initializes objects in the range [first,last).
+ * @param __first A forward iterator.
+ * @param __last A forward iterator.
+ */
template <typename _ForwardIterator>
inline void
uninitialized_value_construct(_ForwardIterator __first,
return __uninitialized_default(__first, __last);
}
+ /**
+ * @brief Value-initializes objects in the range [first,first+count).
+ * @param __first A forward iterator.
+ * @param __count The number of objects to construct.
+ * @return __result + __count
+ */
template <typename _ForwardIterator, typename _Size>
inline _ForwardIterator
uninitialized_value_construct_n(_ForwardIterator __first, _Size __count)
return __uninitialized_default_n(__first, __count);
}
+ /**
+ * @brief Move-construct from the range [first,last) into result.
+ * @param __first An input iterator.
+ * @param __last An input iterator.
+ * @param __result An output iterator.
+ * @return __result + (__first - __last)
+ */
template <typename _InputIterator, typename _ForwardIterator>
inline _ForwardIterator
uninitialized_move(_InputIterator __first, _InputIterator __last,
_GLIBCXX_MAKE_MOVE_ITERATOR(__last), __result);
}
+ /**
+ * @brief Move-construct from the range [first,first+count) into result.
+ * @param __first An input iterator.
+ * @param __count The number of objects to initialize.
+ * @param __result An output iterator.
+ * @return __result + __count
+ */
template <typename _InputIterator, typename _Size, typename _ForwardIterator>
inline pair<_InputIterator, _ForwardIterator>
uninitialized_move_n(_InputIterator __first, _Size __count,
#endif // C++17
#if __cplusplus >= 201103L
+ /// @cond undocumented
+
template<typename _Tp, typename _Up, typename _Allocator>
inline void
__relocate_object_a(_Tp* __restrict __dest, _Up* __restrict __orig,
std::__niter_base(__last),
std::__niter_base(__result), __alloc);
}
+
+ /// @endcond
#endif
+ // @} group memory
+
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
#pragma GCC diagnostic pop
#endif
- /// Primary template of default_delete, used by unique_ptr
+ /// Primary template of default_delete, used by unique_ptr for single objects
template<typename _Tp>
struct default_delete
{
/** @brief Converting constructor.
*
- * Allows conversion from a deleter for arrays of another type, @p _Up,
- * only if @p _Up* is convertible to @p _Tp*.
+ * Allows conversion from a deleter for objects of another type, `_Up`,
+ * only if `_Up*` is convertible to `_Tp*`.
*/
template<typename _Up, typename = typename
enable_if<is_convertible<_Up*, _Tp*>::value>::type>
default_delete(const default_delete<_Up>&) noexcept { }
- /// Calls @c delete @p __ptr
+ /// Calls `delete __ptr`
void
operator()(_Tp* __ptr) const
{
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// DR 740 - omit specialization for array objects with a compile time length
- /// Specialization for arrays, default_delete.
+
+ /// Specialization of default_delete for arrays, used by `unique_ptr<T[]>`
template<typename _Tp>
struct default_delete<_Tp[]>
{
/** @brief Converting constructor.
*
* Allows conversion from a deleter for arrays of another type, such as
- * a const-qualified version of @p _Tp.
+ * a const-qualified version of `_Tp`.
*
- * Conversions from types derived from @c _Tp are not allowed because
- * it is unsafe to @c delete[] an array of derived types through a
+ * Conversions from types derived from `_Tp` are not allowed because
+ * it is undefined to `delete[]` an array of derived types through a
* pointer to the base type.
*/
template<typename _Up, typename = typename
enable_if<is_convertible<_Up(*)[], _Tp(*)[]>::value>::type>
default_delete(const default_delete<_Up[]>&) noexcept { }
- /// Calls @c delete[] @p __ptr
+ /// Calls `delete[] __ptr`
template<typename _Up>
typename enable_if<is_convertible<_Up(*)[], _Tp(*)[]>::value>::type
operator()(_Up* __ptr) const
}
};
+ /// @cond undocumented
+
template <typename _Tp, typename _Dp>
class __uniq_ptr_impl
{
private:
tuple<pointer, _Dp> _M_t;
};
+ /// @endcond
/// 20.7.1.2 unique_ptr for single objects.
template <typename _Tp, typename _Dp = default_delete<_Tp>>
/// @relates unique_ptr @{
+ /// Swap overload for unique_ptr
template<typename _Tp, typename _Dp>
inline
#if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11
unique_ptr<_Tp, _Dp>&) = delete;
#endif
+ /// Equality operator for unique_ptr objects, compares the owned pointers.
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
_GLIBCXX_NODISCARD inline bool
const unique_ptr<_Up, _Ep>& __y)
{ return __x.get() == __y.get(); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator==(const unique_ptr<_Tp, _Dp>& __x, nullptr_t) noexcept
{ return !__x; }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator==(nullptr_t, const unique_ptr<_Tp, _Dp>& __x) noexcept
{ return !__x; }
+ /// Inequality operator for unique_ptr objects, compares the owned pointers
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
_GLIBCXX_NODISCARD inline bool
const unique_ptr<_Up, _Ep>& __y)
{ return __x.get() != __y.get(); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator!=(const unique_ptr<_Tp, _Dp>& __x, nullptr_t) noexcept
{ return (bool)__x; }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator!=(nullptr_t, const unique_ptr<_Tp, _Dp>& __x) noexcept
{ return (bool)__x; }
+ /// Relational operator for unique_ptr objects, compares the owned pointers
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
_GLIBCXX_NODISCARD inline bool
return std::less<_CT>()(__x.get(), __y.get());
}
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator<(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
nullptr);
}
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator<(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
__x.get());
}
+ /// Relational operator for unique_ptr objects, compares the owned pointers
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
_GLIBCXX_NODISCARD inline bool
const unique_ptr<_Up, _Ep>& __y)
{ return !(__y < __x); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator<=(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
{ return !(nullptr < __x); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator<=(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
{ return !(__x < nullptr); }
+ /// Relational operator for unique_ptr objects, compares the owned pointers
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
_GLIBCXX_NODISCARD inline bool
const unique_ptr<_Up, _Ep>& __y)
{ return (__y < __x); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator>(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
__x.get());
}
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator>(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
nullptr);
}
+ /// Relational operator for unique_ptr objects, compares the owned pointers
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
_GLIBCXX_NODISCARD inline bool
const unique_ptr<_Up, _Ep>& __y)
{ return !(__x < __y); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator>=(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
{ return !(__x < nullptr); }
+ /// unique_ptr comparison with nullptr
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator>=(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
*
* The header @c new defines several functions to manage dynamic memory and
* handling memory allocation errors; see
- * http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#4 for more.
+ * https://gcc.gnu.org/onlinedocs/libstdc++/manual/dynamic_memory.html
+ * for more.
*/
#ifndef _NEW
#if __cplusplus > 201703L
namespace std
{
+ /// Tag type used to declare a class-specific operator delete that can
+ /// invoke the destructor before deallocating the memory.
struct destroying_delete_t
{
explicit destroying_delete_t() = default;
};
+ /// Tag variable of type destroying_delete_t.
inline constexpr destroying_delete_t destroying_delete{};
}
// Only define the feature test macro if the compiler supports the feature:
projects / gcc.git / commitdiff