Skip to content

R
riscv-gcc-1
Commit c05ab418 by Jonathan Wakely Committed by Jonathan Wakely
Options

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
parent d16250de
Showing with 51 additions and 6 deletions
libstdc++-v3/ChangeLog
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.
......
libstdc++-v3/config/allocator/new_allocator_base.h
......@@ -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>
......
libstdc++-v3/include/std/memory
......@@ -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
......
libstdc++-v3/include/std/scoped_allocator
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment