Improve API docs for <memory> and <scoped_allocator>
* config/allocator/new_allocator_base.h (__allocator_base): Add workaround for Doxygen bug #6945. * include/std/memory: Improve docs. Define group for pointer safety. * include/std/scoped_allocator: Improve docs. Use "undocumented" conditional to suppress documentation for implementation details. From-SVN: r270807
This commit is contained in:
Jonathan Wakely
Jonathan Wakely
parent
d16250de4a
commit
c05ab418b3
|
|
@ -1,5 +1,11 @@
|
|||
2019-05-02 Jonathan Wakely <jwakely@redhat.com>
|
||||
|
||||
* config/allocator/new_allocator_base.h (__allocator_base): Add
|
||||
workaround for Doxygen bug #6945.
|
||||
* include/std/memory: Improve docs. Define group for pointer safety.
|
||||
* include/std/scoped_allocator: Improve docs. Use "undocumented"
|
||||
conditional to suppress documentation for implementation details.
|
||||
|
||||
* include/bits/specfun.h: Improve docs.
|
||||
* include/tr1/cmath: Likewise. Fix nesting of preprocessor conditions
|
||||
and namespaces.
|
||||
|
|
|
|||
|
|
@ -37,11 +37,11 @@ namespace std
|
|||
{
|
||||
/**
|
||||
* @brief An alias to the base class for std::allocator.
|
||||
* @ingroup allocators
|
||||
*
|
||||
* Used to set the std::allocator base class to
|
||||
* __gnu_cxx::new_allocator.
|
||||
*
|
||||
* @ingroup allocators
|
||||
* @tparam _Tp Type of allocated object.
|
||||
*/
|
||||
template<typename _Tp>
|
||||
|
|
|
|||
|
|
@ -38,6 +38,7 @@
|
|||
|
||||
/** @file include/memory
|
||||
* This is a Standard C++ Library header.
|
||||
* @ingroup memory
|
||||
*/
|
||||
|
||||
#ifndef _GLIBCXX_MEMORY
|
||||
|
|
@ -100,19 +101,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
|
||||
/**
|
||||
* @brief Fit aligned storage in buffer.
|
||||
*
|
||||
* [ptr.align]
|
||||
* @ingroup memory
|
||||
*
|
||||
* This function tries to fit @a __size bytes of storage with alignment
|
||||
* @a __align into the buffer @a __ptr of size @a __space bytes. If such
|
||||
* a buffer fits then @a __ptr is changed to point to the first byte of the
|
||||
* aligned storage and @a __space is reduced by the bytes used for alignment.
|
||||
*
|
||||
* C++11 20.6.5 [ptr.align]
|
||||
*
|
||||
* @param __align A fundamental or extended alignment value.
|
||||
* @param __size Size of the aligned storage required.
|
||||
* @param __ptr Pointer to a buffer of @a __space bytes.
|
||||
* @param __space Size of the buffer pointed to by @a __ptr.
|
||||
* @return the updated pointer if the aligned storage fits, otherwise nullptr.
|
||||
*
|
||||
*/
|
||||
inline void*
|
||||
align(size_t __align, size_t __size, void*& __ptr, size_t& __space) noexcept
|
||||
|
|
@ -136,28 +139,52 @@ align(size_t __align, size_t __size, void*& __ptr, size_t& __space) noexcept
|
|||
}
|
||||
}
|
||||
|
||||
// 20.7.4 [util.dynamic.safety], pointer safety
|
||||
/** @defgroup ptr_safety Pointer Safety and Garbage Collection
|
||||
* @ingroup memory
|
||||
*
|
||||
* Utilities to assist with garbage collection in an implementation
|
||||
* that supports <em>strict pointer safety</em>.
|
||||
* This implementation only supports <em>relaxed pointer safety</em>
|
||||
* and so these functions have no effect.
|
||||
*
|
||||
* C++11 20.6.4 [util.dynamic.safety], Pointer safety
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/// Constants representing the different types of pointer safety.
|
||||
enum class pointer_safety { relaxed, preferred, strict };
|
||||
|
||||
/// Inform a garbage collector that an object is still in use.
|
||||
inline void
|
||||
declare_reachable(void*) { }
|
||||
|
||||
/// Unregister an object previously registered with declare_reachable.
|
||||
template <typename _Tp>
|
||||
inline _Tp*
|
||||
undeclare_reachable(_Tp* __p) { return __p; }
|
||||
|
||||
/// Inform a garbage collector that a region of memory need not be traced.
|
||||
inline void
|
||||
declare_no_pointers(char*, size_t) { }
|
||||
|
||||
/// Unregister a range previously registered with declare_no_pointers.
|
||||
inline void
|
||||
undeclare_no_pointers(char*, size_t) { }
|
||||
|
||||
/// The type of pointer safety supported by the implementation.
|
||||
inline pointer_safety
|
||||
get_pointer_safety() noexcept { return pointer_safety::relaxed; }
|
||||
// @}
|
||||
|
||||
#if __cplusplus > 201703L
|
||||
/// Inform the compiler that a pointer is aligned.
|
||||
/** @brief Inform the compiler that a pointer is aligned.
|
||||
*
|
||||
* @tparam _Align An alignment value (i.e. a power of two)
|
||||
* @tparam _Tp An object type
|
||||
* @param __ptr A pointer that is aligned to _Align
|
||||
* @ingroup memory
|
||||
*/
|
||||
template<size_t _Align, class _Tp>
|
||||
[[nodiscard,__gnu__::__always_inline__]]
|
||||
constexpr _Tp* assume_aligned(_Tp* __ptr)
|
||||
|
|
@ -176,6 +203,9 @@ get_pointer_safety() noexcept { return pointer_safety::relaxed; }
|
|||
template<typename _Tp, typename _Up>
|
||||
struct __is_pair<const pair<_Tp, _Up>> : true_type { };
|
||||
|
||||
/** @addtogroup allocators
|
||||
* @{
|
||||
*/
|
||||
template<typename _Tp, typename __ = _Require<__not_<__is_pair<_Tp>>>,
|
||||
typename _Alloc, typename... _Args>
|
||||
constexpr auto
|
||||
|
|
@ -358,6 +388,7 @@ get_pointer_safety() noexcept { return pointer_safety::relaxed; }
|
|||
return ::new(__vp) _Tp(std::make_obj_using_allocator<_Tp>(__a,
|
||||
std::forward<_Args>(__args)...));
|
||||
}
|
||||
// @}
|
||||
|
||||
#endif // C++2a
|
||||
|
||||
|
|
|
|||
|
|
@ -24,6 +24,7 @@
|
|||
|
||||
/** @file include/scoped_allocator
|
||||
* This is a Standard C++ Library header.
|
||||
* @ingroup allocators
|
||||
*/
|
||||
|
||||
#ifndef _SCOPED_ALLOCATOR
|
||||
|
|
@ -49,6 +50,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
* @{
|
||||
*/
|
||||
|
||||
/// @cond undocumented
|
||||
|
||||
template<typename _Alloc>
|
||||
using __outer_allocator_t
|
||||
= decltype(std::declval<_Alloc>().outer_allocator());
|
||||
|
|
@ -75,6 +78,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
{ return __base::_S_outermost(__a.outer_allocator()); }
|
||||
};
|
||||
|
||||
/// Implementation of the OUTERMOST pseudofunction
|
||||
template<typename _Alloc>
|
||||
inline typename __outermost_type<_Alloc>::type&
|
||||
__outermost(_Alloc& __a)
|
||||
|
|
@ -164,7 +168,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
__type _M_inner;
|
||||
};
|
||||
|
||||
/// Primary class template.
|
||||
/// @endcond
|
||||
|
||||
/// An adaptor to recursively pass an allocator to the objects it constructs
|
||||
template<typename _OuterAlloc, typename... _InnerAllocs>
|
||||
class scoped_allocator_adaptor
|
||||
: public _OuterAlloc
|
||||
|
|
@ -484,6 +490,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
#endif // C++17
|
||||
};
|
||||
|
||||
/// @related std::scoped_allocator_adaptor
|
||||
template <typename _OutA1, typename _OutA2, typename... _InA>
|
||||
inline bool
|
||||
operator==(const scoped_allocator_adaptor<_OutA1, _InA...>& __a,
|
||||
|
|
@ -493,6 +500,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
|||
&& __a._M_inner == __b._M_inner;
|
||||
}
|
||||
|
||||
/// @related std::scoped_allocator_adaptor
|
||||
template <typename _OutA1, typename _OutA2, typename... _InA>
|
||||
inline bool
|
||||
operator!=(const scoped_allocator_adaptor<_OutA1, _InA...>& __a,
|
||||
|
|
|
|||
Loading…
Reference in New Issue