libstdc++: Improve doxygen docs for <memory_resource>

libstdc++-v3/ChangeLog:

	* include/bits/memory_resource.h: Improve doxygen comments.
	* include/std/memory_resource: Likewise.

diff --git a/libstdc++-v3/include/bits/memory_resource.h b/libstdc++-v3/include/bits/memory_resource.h
index 1b9e51ddbbd4b9b88d8bb2b1a35776545915b1b6..f12555d42158eefba38495688a06e28f9845a2f3 100644 (file)
--- a/libstdc++-v3/include/bits/memory_resource.h
+++ b/libstdc++-v3/include/bits/memory_resource.h
@@ -53,6 +53,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 namespace pmr
 {
   /// Class memory_resource
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class memory_resource
   {
     static constexpr size_t _S_max_align = alignof(max_align_t);
@@ -104,6 +109,13 @@ namespace pmr
 #endif
 
   // C++17 23.12.3 Class template polymorphic_allocator
+
+  /// Class template polymorphic_allocator
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   template<typename _Tp>
     class polymorphic_allocator
     {

diff --git a/libstdc++-v3/include/std/memory_resource b/libstdc++-v3/include/std/memory_resource
index 0085926247080290b8b5a60520676c4eaf8a99fd..fdfc23c95ed30555e866f5393c63b808c0d2eb07 100644 (file)
--- a/libstdc++-v3/include/std/memory_resource
+++ b/libstdc++-v3/include/std/memory_resource
@@ -24,6 +24,9 @@
 
 /** @file include/memory_resource
  *  This is a Standard C++ Library header.
+ *
+ *  This header declares the @ref pmr (std::pmr) memory resources.
+ *  @ingroup pmr
  */
 
 #ifndef _GLIBCXX_MEMORY_RESOURCE
@@ -35,6 +38,25 @@
 
 #if __cplusplus >= 201703L
 
+/**
+ * @defgroup pmr Polymorphic memory resources
+ *
+ * @anchor pmr
+ * @ingroup memory
+ * @since C++17
+ *
+ * Memory resources are classes that implement the `std::pmr::memory_resource`
+ * interface for allocating and deallocating memory. Unlike traditional C++
+ * allocators, memory resources are not value types and are used via pointers
+ * to the abstract base class. They are only responsible for allocating and
+ * deallocating, not for construction and destruction of objects. As a result,
+ * memory resources just allocate raw memory as type `void*` and are not
+ * templates that allocate/deallocate and construct/destroy a specific type.
+ *
+ * The class template `std::pmr::polymorphic_allocator` is an allocator that
+ * uses a memory resource for its allocations.
+ */
+
 #include <bits/memory_resource.h>
 #include <vector>                      // vector
 #include <shared_mutex>                        // shared_mutex
@@ -63,6 +85,11 @@ namespace pmr
   // Global memory resources
 
   /// A pmr::memory_resource that uses `new` to allocate memory
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   [[nodiscard, __gnu__::__returns_nonnull__, __gnu__::__const__]]
   memory_resource*
   new_delete_resource() noexcept;
@@ -91,6 +118,11 @@ namespace pmr
   class monotonic_buffer_resource;
 
   /// Parameters for tuning a pool resource's behaviour.
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   struct pool_options
   {
     /** @brief Upper limit on number of blocks in a chunk.
@@ -152,6 +184,11 @@ namespace pmr
 
 #ifdef _GLIBCXX_HAS_GTHREADS
   /// A thread-safe memory resource that manages pools of fixed-size blocks.
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class synchronized_pool_resource : public memory_resource
   {
   public:
@@ -218,6 +255,11 @@ namespace pmr
 #endif
 
   /// A non-thread-safe memory resource that manages pools of fixed-size blocks.
+  /**
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class unsynchronized_pool_resource : public memory_resource
   {
   public:
@@ -275,6 +317,27 @@ namespace pmr
     _Pool* _M_pools = nullptr;
   };
 
+  /// A memory resource that allocates from a fixed-size buffer.
+  /**
+   * The main feature of a `pmr::monotonic_buffer_resource` is that its
+   * `do_deallocate` does nothing. This makes it very fast because there is no
+   * need to manage a free list, and every allocation simply returns a new
+   * block of memory, rather than searching for a suitably-sized free block.
+   * Because deallocating is a no-op, the amount of memory used by the resource
+   * only grows until `release()` (or the destructor) is called to return all
+   * memory to upstream.
+   *
+   * A `monotonic_buffer_resource` can be initialized with a buffer that
+   * will be used to satisfy all allocation requests, until the buffer is full.
+   * After that a new buffer will be allocated from the upstream resource.
+   * By using a stack buffer and `pmr::null_memory_resource()` as the upstream
+   * you can get a memory resource that only uses the stack and never
+   * dynamically allocates.
+   *
+   * @ingroup pmr
+   * @headerfile memory_resource
+   * @since C++17
+   */
   class monotonic_buffer_resource : public memory_resource
   {
   public: