[mem.res] - C++14 → C++17

Files changed (1) hide show

tmp/tmp0twqi0v3/{from.md → to.md} +849 -0

tmp/tmp0twqi0v3/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,849 @@

+## Memory resources <a id="mem.res">[[mem.res]]</a>
+### Header `<memory_resource>` synopsis <a id="mem.res.syn">[[mem.res.syn]]</a>
+``` cpp
+namespace std::pmr {
+  // [mem.res.class], class memory_resource
+  class memory_resource;
+  bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
+  bool operator!=(const memory_resource& a, const memory_resource& b) noexcept;
+  // [mem.poly.allocator.class], class template polymorphic_allocator
+  template <class Tp> class polymorphic_allocator;
+  template <class T1, class T2>
+    bool operator==(const polymorphic_allocator<T1>& a,
+                    const polymorphic_allocator<T2>& b) noexcept;
+  template <class T1, class T2>
+    bool operator!=(const polymorphic_allocator<T1>& a,
+                    const polymorphic_allocator<T2>& b) noexcept;
+  // [mem.res.global], global memory resources
+  memory_resource* new_delete_resource() noexcept;
+  memory_resource* null_memory_resource() noexcept;
+  memory_resource* set_default_resource(memory_resource* r) noexcept;
+  memory_resource* get_default_resource() noexcept;
+  // [mem.res.pool], pool resource classes
+  struct pool_options;
+  class synchronized_pool_resource;
+  class unsynchronized_pool_resource;
+  class monotonic_buffer_resource;
+}
+```
+### Class `memory_resource` <a id="mem.res.class">[[mem.res.class]]</a>
+The `memory_resource` class is an abstract interface to an unbounded set
+of classes encapsulating memory resources.
+``` cpp
+class memory_resource {
+  static constexpr size_t max_align = alignof(max_align_t); // exposition only
+public:
+  virtual ~memory_resource();
+  void* allocate(size_t bytes, size_t alignment = max_align);
+  void deallocate(void* p, size_t bytes, size_t alignment = max_align);
+  bool is_equal(const memory_resource& other) const noexcept;
+private:
+  virtual void* do_allocate(size_t bytes, size_t alignment) = 0;
+  virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0;
+  virtual bool do_is_equal(const memory_resource& other) const noexcept = 0;
+};
+```
+#### `memory_resource` public member functions <a id="mem.res.public">[[mem.res.public]]</a>
+``` cpp
+~memory_resource();
+```
+*Effects:* Destroys this `memory_resource`.
+``` cpp
+void* allocate(size_t bytes, size_t alignment = max_align);
+```
+*Effects:* Equivalent to: `return do_allocate(bytes, alignment);`
+``` cpp
+void deallocate(void* p, size_t bytes, size_t alignment = max_align);
+```
+*Effects:* Equivalent to: `do_deallocate(p, bytes, alignment);`
+``` cpp
+bool is_equal(const memory_resource& other) const noexcept;
+```
+*Effects:* Equivalent to: `return do_is_equal(other);`
+#### `memory_resource` private virtual member functions <a id="mem.res.private">[[mem.res.private]]</a>
+``` cpp
+virtual void* do_allocate(size_t bytes, size_t alignment) = 0;
+```
+*Requires:* `alignment` shall be a power of two.
+*Returns:* A derived class shall implement this function to return a
+pointer to allocated storage ([[basic.stc.dynamic.deallocation]]) with
+a size of at least `bytes`. The returned storage is aligned to the
+specified alignment, if such alignment is supported ([[basic.align]]);
+otherwise it is aligned to `max_align`.
+*Throws:* A derived class implementation shall throw an appropriate
+exception if it is unable to allocate memory with the requested size and
+alignment.
+``` cpp
+virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0;
+```
+*Requires:* `p` shall have been returned from a prior call to
+`allocate(bytes, alignment)` on a memory resource equal to `*this`, and
+the storage at `p` shall not yet have been deallocated.
+*Effects:* A derived class shall implement this function to dispose of
+allocated storage.
+*Throws:* Nothing.
+``` cpp
+virtual bool do_is_equal(const memory_resource& other) const noexcept = 0;
+```
+*Returns:* A derived class shall implement this function to return
+`true` if memory allocated from `this` can be deallocated from `other`
+and vice-versa, otherwise `false`.
+[*Note 1*: The most-derived type of `other` might not match the type of
+`this`. For a derived class `D`, a typical implementation of this
+function will immediately return `false` if
+`dynamic_cast<const D*>(&other) == nullptr`. — *end note*]
+#### `memory_resource` equality <a id="mem.res.eq">[[mem.res.eq]]</a>
+``` cpp
+bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
+```
+*Returns:* `&a == &b || a.is_equal(b)`.
+``` cpp
+bool operator!=(const memory_resource& a, const memory_resource& b) noexcept;
+```
+*Returns:* `!(a == b)`.
+### Class template `polymorphic_allocator` <a id="mem.poly.allocator.class">[[mem.poly.allocator.class]]</a>
+A specialization of class template `pmr::polymorphic_allocator` conforms
+to the `Allocator` requirements ([[allocator.requirements]]).
+Constructed with different memory resources, different instances of the
+same specialization of `pmr::polymorphic_allocator` can exhibit entirely
+different allocation behavior. This runtime polymorphism allows objects
+that use `polymorphic_allocator` to behave as if they used different
+allocator types at run time even though they use the same static
+allocator type.
+``` cpp
+template <class Tp>
+class polymorphic_allocator {
+  memory_resource* memory_rsrc; // exposition only
+public:
+  using value_type = Tp;
+  // [mem.poly.allocator.ctor], constructors
+  polymorphic_allocator() noexcept;
+  polymorphic_allocator(memory_resource* r);
+  polymorphic_allocator(const polymorphic_allocator& other) = default;
+  template <class U>
+    polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
+  polymorphic_allocator&
+    operator=(const polymorphic_allocator& rhs) = delete;
+  // [mem.poly.allocator.mem], member functions
+  Tp* allocate(size_t n);
+  void deallocate(Tp* p, size_t n);
+  template <class T, class... Args>
+  void construct(T* p, Args&&... args);
+  template <class T1, class T2, class... Args1, class... Args2>
+    void construct(pair<T1,T2>* p, piecewise_construct_t,
+                   tuple<Args1...> x, tuple<Args2...> y);
+  template <class T1, class T2>
+    void construct(pair<T1,T2>* p);
+  template <class T1, class T2, class U, class V>
+    void construct(pair<T1,T2>* p, U&& x, V&& y);
+  template <class T1, class T2, class U, class V>
+    void construct(pair<T1,T2>* p, const pair<U, V>& pr);
+  template <class T1, class T2, class U, class V>
+    void construct(pair<T1,T2>* p, pair<U, V>&& pr);
+  template <class T>
+    void destroy(T* p);
+  polymorphic_allocator select_on_container_copy_construction() const;
+  memory_resource* resource() const;
+};
+```
+#### `polymorphic_allocator` constructors <a id="mem.poly.allocator.ctor">[[mem.poly.allocator.ctor]]</a>
+``` cpp
+polymorphic_allocator() noexcept;
+```
+*Effects:* Sets `memory_rsrc` to `get_default_resource()`.
+``` cpp
+polymorphic_allocator(memory_resource* r);
+```
+*Requires:* `r` is non-null.
+*Effects:* Sets `memory_rsrc` to `r`.
+*Throws:* Nothing.
+[*Note 1*: This constructor provides an implicit conversion from
+`memory_resource*`. — *end note*]
+``` cpp
+template <class U>
+  polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
+```
+*Effects:* Sets `memory_rsrc` to `other.resource()`.
+#### `polymorphic_allocator` member functions <a id="mem.poly.allocator.mem">[[mem.poly.allocator.mem]]</a>
+``` cpp
+Tp* allocate(size_t n);
+```
+*Returns:* Equivalent to
+``` cpp
+return static_cast<Tp*>(memory_rsrc->allocate(n * sizeof(Tp), alignof(Tp)));
+```
+``` cpp
+void deallocate(Tp* p, size_t n);
+```
+*Requires:* `p` was allocated from a memory resource `x`, equal to
+`*memory_rsrc`, using `x.allocate(n * sizeof(Tp), alignof(Tp))`.
+*Effects:* Equivalent to
+`memory_rsrc->deallocate(p, n * sizeof(Tp), alignof(Tp))`.
+*Throws:* Nothing.
+``` cpp
+template <class T, class... Args>
+  void construct(T* p, Args&&... args);
+```
+*Requires:* Uses-allocator construction of `T` with allocator
+`resource()` (see  [[allocator.uses.construction]]) and constructor
+arguments `std::forward<Args>(args)...` is well-formed.
+[*Note 1*: Uses-allocator construction is always well formed for types
+that do not use allocators. — *end note*]
+*Effects:* Construct a `T` object in the storage whose address is
+represented by `p` by uses-allocator construction with allocator
+`resource()` and constructor arguments `std::forward<Args>(args)...`.
+*Throws:* Nothing unless the constructor for `T` throws.
+``` cpp
+template <class T1, class T2, class... Args1, class... Args2>
+  void construct(pair<T1,T2>* p, piecewise_construct_t,
+                 tuple<Args1...> x, tuple<Args2...> y);
+```
+[*Note 2*: This method and the `construct` methods that follow are
+overloads for piecewise construction of
+pairs ([[pairs.pair]]). — *end note*]
+*Effects:* Let `xprime` be a `tuple` constructed from `x` according to
+the appropriate rule from the following list.
+[*Note 3*: The following description can be summarized as constructing
+a `pair<T1, T2>` object in the storage whose address is represented by
+`p`, as if by separate uses-allocator construction with allocator
+`resource()` ([[allocator.uses.construction]]) of `p->first` using the
+elements of `x` and `p->second` using the elements of
+`y`. — *end note*]
+- If `uses_allocator_v<T1,memory_resource*>` is `false`
+  and `is_constructible_v<T1,Args1...>` is `true`,
+  then `xprime` is `x`.
+- Otherwise, if `uses_allocator_v<T1,memory_resource*>` is `true`
+  and `is_constructible_v<T1,allocator_arg_t,memory_resource*,Args1...>`
+  is `true`,
+  then `xprime` is
+  `tuple_cat(make_tuple(allocator_arg, resource()), std::move(x))`.
+- Otherwise, if `uses_allocator_v<T1,memory_resource*>` is `true`
+  and `is_constructible_v<T1,Args1...,memory_resource*>` is `true`,
+  then `xprime` is `tuple_cat(std::move(x), make_tuple(resource()))`.
+- Otherwise the program is ill formed.
+Let `yprime` be a tuple constructed from `y` according to the
+appropriate rule from the following list:
+- If `uses_allocator_v<T2,memory_resource*>` is `false`
+  and `is_constructible_v<T2,Args2...>` is `true`,
+  then `yprime` is `y`.
+- Otherwise, if `uses_allocator_v<T2,memory_resource*>` is `true`
+  and `is_constructible_v<T2,allocator_arg_t,memory_resource*,Args2...>`
+  is `true`,
+  then `yprime` is
+  `tuple_cat(make_tuple(allocator_arg, resource()), std::move(y))`.
+- Otherwise, if `uses_allocator_v<T2,memory_resource*>` is `true`
+  and `is_constructible_v<T2,Args2...,memory_resource*>` is `true`,
+  then `yprime` is `tuple_cat(std::move(y), make_tuple(resource()))`.
+- Otherwise the program is ill formed.
+Then, using `piecewise_construct`, `xprime`, and `yprime` as the
+constructor arguments, this function constructs a `pair<T1, T2>` object
+in the storage whose address is represented by `p`.
+``` cpp
+template <class T1, class T2>
+  void construct(pair<T1,T2>* p);
+```
+*Effects:* Equivalent to:
+``` cpp
+construct(p, piecewise_construct, tuple<>(), tuple<>());
+```
+``` cpp
+template <class T1, class T2, class U, class V>
+  void construct(pair<T1,T2>* p, U&& x, V&& y);
+```
+*Effects:* Equivalent to:
+``` cpp
+construct(p, piecewise_construct,
+          forward_as_tuple(std::forward<U>(x)),
+          forward_as_tuple(std::forward<V>(y)));
+```
+``` cpp
+template <class T1, class T2, class U, class V>
+  void construct(pair<T1,T2>* p, const pair<U, V>& pr);
+```
+*Effects:* Equivalent to:
+``` cpp
+construct(p, piecewise_construct,
+          forward_as_tuple(pr.first),
+          forward_as_tuple(pr.second));
+```
+``` cpp
+template <class T1, class T2, class U, class V>
+  void construct(pair<T1,T2>* p, pair<U, V>&& pr);
+```
+*Effects:* Equivalent to:
+``` cpp
+construct(p, piecewise_construct,
+          forward_as_tuple(std::forward<U>(pr.first)),
+          forward_as_tuple(std::forward<V>(pr.second)));
+```
+``` cpp
+template <class T>
+  void destroy(T* p);
+```
+*Effects:* As if by `p->T̃()`.
+``` cpp
+polymorphic_allocator select_on_container_copy_construction() const;
+```
+*Returns:* `polymorphic_allocator()`.
+[*Note 4*: The memory resource is not propagated. — *end note*]
+``` cpp
+memory_resource* resource() const;
+```
+*Returns:* `memory_rsrc`.
+#### `polymorphic_allocator` equality <a id="mem.poly.allocator.eq">[[mem.poly.allocator.eq]]</a>
+``` cpp
+template <class T1, class T2>
+  bool operator==(const polymorphic_allocator<T1>& a,
+                  const polymorphic_allocator<T2>& b) noexcept;
+```
+*Returns:* `*a.resource() == *b.resource()`.
+``` cpp
+template <class T1, class T2>
+  bool operator!=(const polymorphic_allocator<T1>& a,
+                  const polymorphic_allocator<T2>& b) noexcept;
+```
+*Returns:* `!(a == b)`.
+### Access to program-wide `memory_resource` objects <a id="mem.res.global">[[mem.res.global]]</a>
+``` cpp
+memory_resource* new_delete_resource() noexcept;
+```
+*Returns:* A pointer to a static-duration object of a type derived from
+`memory_resource` that can serve as a resource for allocating memory
+using `::operator new` and `::operator delete`. The same value is
+returned every time this function is called. For a return value `p` and
+a memory resource `r`, `p->is_equal(r)` returns `&r == p`.
+``` cpp
+memory_resource* null_memory_resource() noexcept;
+```
+*Returns:* A pointer to a static-duration object of a type derived from
+`memory_resource` for which `allocate()` always throws `bad_alloc` and
+for which `deallocate()` has no effect. The same value is returned every
+time this function is called. For a return value `p` and a memory
+resource `r`, `p->is_equal(r)` returns `&r == p`.
+The *default memory resource pointer* is a pointer to a memory resource
+that is used by certain facilities when an explicit memory resource is
+not supplied through the interface. Its initial value is the return
+value of `new_delete_resource()`.
+``` cpp
+memory_resource* set_default_resource(memory_resource* r) noexcept;
+```
+*Effects:* If `r` is non-null, sets the value of the default memory
+resource pointer to `r`, otherwise sets the default memory resource
+pointer to `new_delete_resource()`.
+*Postconditions:* `get_default_resource() == r`.
+*Returns:* The previous value of the default memory resource pointer.
+*Remarks:* Calling the `set_default_resource` and `get_default_resource`
+functions shall not incur a data race. A call to the
+`set_default_resource` function shall synchronize with subsequent calls
+to the `set_default_resource` and `get_default_resource` functions.
+``` cpp
+memory_resource* get_default_resource() noexcept;
+```
+*Returns:* The current value of the default memory resource pointer.
+### Pool resource classes <a id="mem.res.pool">[[mem.res.pool]]</a>
+#### Classes `synchronized_pool_resource` and `unsynchronized_pool_resource` <a id="mem.res.pool.overview">[[mem.res.pool.overview]]</a>
+The `synchronized_pool_resource` and `unsynchronized_pool_resource`
+classes (collectively called *pool resource classes*) are
+general-purpose memory resources having the following qualities:
+- Each resource frees its allocated memory on destruction, even if
+  `deallocate` has not been called for some of the allocated blocks.
+- A pool resource consists of a collection of *pools*, serving requests
+  for different block sizes. Each individual pool manages a collection
+  of *chunks* that are in turn divided into blocks of uniform size,
+  returned via calls to `do_allocate`. Each call to
+  `do_allocate(size, alignment)` is dispatched to the pool serving the
+  smallest blocks accommodating at least `size` bytes.
+- When a particular pool is exhausted, allocating a block from that pool
+  results in the allocation of an additional chunk of memory from the
+  *upstream allocator* (supplied at construction), thus replenishing the
+  pool. With each successive replenishment, the chunk size obtained
+  increases geometrically. \[*Note 1*: By allocating memory in chunks,
+  the pooling strategy increases the chance that consecutive allocations
+  will be close together in memory. — *end note*]
+- Allocation requests that exceed the largest block size of any pool are
+  fulfilled directly from the upstream allocator.
+- A `pool_options` struct may be passed to the pool resource
+  constructors to tune the largest block size and the maximum chunk
+  size.
+A `synchronized_pool_resource` may be accessed from multiple threads
+without external synchronization and may have thread-specific pools to
+reduce synchronization costs. An `unsynchronized_pool_resource` class
+may not be accessed from multiple threads simultaneously and thus avoids
+the cost of synchronization entirely in single-threaded applications.
+``` cpp
+struct pool_options {
+  size_t max_blocks_per_chunk = 0;
+  size_t largest_required_pool_block = 0;
+};
+class synchronized_pool_resource : public memory_resource {
+public:
+  synchronized_pool_resource(const pool_options& opts,
+                             memory_resource* upstream);
+  synchronized_pool_resource()
+      : synchronized_pool_resource(pool_options(), get_default_resource()) {}
+  explicit synchronized_pool_resource(memory_resource* upstream)
+      : synchronized_pool_resource(pool_options(), upstream) {}
+  explicit synchronized_pool_resource(const pool_options& opts)
+      : synchronized_pool_resource(opts, get_default_resource()) {}
+  synchronized_pool_resource(const synchronized_pool_resource&) = delete;
+  virtual ~synchronized_pool_resource();
+  synchronized_pool_resource&
+    operator=(const synchronized_pool_resource&) = delete;
+  void release();
+  memory_resource* upstream_resource() const;
+  pool_options options() const;
+protected:
+  void *do_allocate(size_t bytes, size_t alignment) override;
+  void do_deallocate(void *p, size_t bytes, size_t alignment) override;
+  bool do_is_equal(const memory_resource& other) const noexcept override;
+};
+class unsynchronized_pool_resource : public memory_resource {
+public:
+  unsynchronized_pool_resource(const pool_options& opts,
+                               memory_resource* upstream);
+  unsynchronized_pool_resource()
+      : unsynchronized_pool_resource(pool_options(), get_default_resource()) {}
+  explicit unsynchronized_pool_resource(memory_resource* upstream)
+      : unsynchronized_pool_resource(pool_options(), upstream) {}
+  explicit unsynchronized_pool_resource(const pool_options& opts)
+      : unsynchronized_pool_resource(opts, get_default_resource()) {}
+  unsynchronized_pool_resource(const unsynchronized_pool_resource&) = delete;
+  virtual ~unsynchronized_pool_resource();
+  unsynchronized_pool_resource&
+    operator=(const unsynchronized_pool_resource&) = delete;
+  void release();
+  memory_resource *upstream_resource() const;
+  pool_options options() const;
+protected:
+  void* do_allocate(size_t bytes, size_t alignment) override;
+  void do_deallocate(void* p, size_t bytes, size_t alignment) override;
+  bool do_is_equal(const memory_resource& other) const noexcept override;
+};
+```
+#### `pool_options` data members <a id="mem.res.pool.options">[[mem.res.pool.options]]</a>
+The members of `pool_options` comprise a set of constructor options for
+pool resources. The effect of each option on the pool resource behavior
+is described below:
+``` cpp
+size_t max_blocks_per_chunk;
+```
+The maximum number of blocks that will be allocated at once from the
+upstream memory resource ([[mem.res.monotonic.buffer]]) to replenish a
+pool. If the value of `max_blocks_per_chunk` is zero or is greater than
+an *implementation-defined* limit, that limit is used instead. The
+implementation may choose to use a smaller value than is specified in
+this field and may use different values for different pools.
+``` cpp
+size_t largest_required_pool_block;
+```
+The largest allocation size that is required to be fulfilled using the
+pooling mechanism. Attempts to allocate a single block larger than this
+threshold will be allocated directly from the upstream memory resource.
+If `largest_required_pool_block` is zero or is greater than an
+*implementation-defined* limit, that limit is used instead. The
+implementation may choose a pass-through threshold larger than specified
+in this field.
+#### Pool resource constructors and destructors <a id="mem.res.pool.ctor">[[mem.res.pool.ctor]]</a>
+``` cpp
+synchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
+unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream);
+```
+*Requires:* `upstream` is the address of a valid memory resource.
+*Effects:* Constructs a pool resource object that will obtain memory
+from `upstream` whenever the pool resource is unable to satisfy a memory
+request from its own internal data structures. The resulting object will
+hold a copy of `upstream`, but will not own the resource to which
+`upstream` points.
+[*Note 1*: The intention is that calls to `upstream->allocate()` will
+be substantially fewer than calls to `this->allocate()` in most
+cases. — *end note*]
+The behavior of the pooling mechanism is tuned according to the value of
+the `opts` argument.
+*Throws:* Nothing unless `upstream->allocate()` throws. It is
+unspecified if, or under what conditions, this constructor calls
+`upstream->allocate()`.
+``` cpp
+virtual ~synchronized_pool_resource();
+virtual ~unsynchronized_pool_resource();
+```
+*Effects:* Calls `release()`.
+#### Pool resource members <a id="mem.res.pool.mem">[[mem.res.pool.mem]]</a>
+``` cpp
+void release();
+```
+*Effects:* Calls `upstream_resource()->deallocate()` as necessary to
+release all allocated memory.
+[*Note 1*: The memory is released back to `upstream_resource()` even if
+`deallocate` has not been called for some of the allocated
+blocks. — *end note*]
+``` cpp
+memory_resource* upstream_resource() const;
+```
+*Returns:* The value of the `upstream` argument provided to the
+constructor of this object.
+``` cpp
+pool_options options() const;
+```
+*Returns:* The options that control the pooling behavior of this
+resource. The values in the returned struct may differ from those
+supplied to the pool resource constructor in that values of zero will be
+replaced with *implementation-defined* defaults, and sizes may be
+rounded to unspecified granularity.
+``` cpp
+void* do_allocate(size_t bytes, size_t alignment) override;
+```
+*Returns:* A pointer to allocated storage
+([[basic.stc.dynamic.deallocation]]) with a size of at least `bytes`.
+The size and alignment of the allocated memory shall meet the
+requirements for a class derived from `memory_resource` ([[mem.res]]).
+*Effects:* If the pool selected for a block of size `bytes` is unable to
+satisfy the memory request from its own internal data structures, it
+will call `upstream_resource()->allocate()` to obtain more memory. If
+`bytes` is larger than that which the largest pool can handle, then
+memory will be allocated using `upstream_resource()->allocate()`.
+*Throws:* Nothing unless `upstream_resource()->allocate()` throws.
+``` cpp
+void do_deallocate(void* p, size_t bytes, size_t alignment) override;
+```
+*Effects:* Returns the memory at `p` to the pool. It is unspecified if,
+or under what circumstances, this operation will result in a call to
+`upstream_resource()->deallocate()`.
+*Throws:* Nothing.
+``` cpp
+bool synchronized_pool_resource::do_is_equal(
+    const memory_resource& other) const noexcept override;
+```
+*Returns:*
+`this == dynamic_cast<const synchronized_pool_resource*>(&other)`.
+``` cpp
+bool unsynchronized_pool_resource::do_is_equal(
+    const memory_resource& other) const noexcept override;
+```
+*Returns:*
+`this == dynamic_cast<const unsynchronized_pool_resource*>(&other)`.
+### Class `monotonic_buffer_resource` <a id="mem.res.monotonic.buffer">[[mem.res.monotonic.buffer]]</a>
+A `monotonic_buffer_resource` is a special-purpose memory resource
+intended for very fast memory allocations in situations where memory is
+used to build up a few objects and then is released all at once when the
+memory resource object is destroyed. It has the following qualities:
+- A call to `deallocate` has no effect, thus the amount of memory
+  consumed increases monotonically until the resource is destroyed.
+- The program can supply an initial buffer, which the allocator uses to
+  satisfy memory requests.
+- When the initial buffer (if any) is exhausted, it obtains additional
+  buffers from an *upstream* memory resource supplied at construction.
+  Each additional buffer is larger than the previous one, following a
+  geometric progression.
+- It is intended for access from one thread of control at a time.
+  Specifically, calls to `allocate` and `deallocate` do not synchronize
+  with one another.
+- It frees the allocated memory on destruction, even if `deallocate` has
+  not been called for some of the allocated blocks.
+``` cpp
+class monotonic_buffer_resource : public memory_resource {
+  memory_resource *upstream_rsrc; // exposition only
+  void *current_buffer;           // exposition only
+  size_t next_buffer_size;        // exposition only
+public:
+  explicit monotonic_buffer_resource(memory_resource *upstream);
+  monotonic_buffer_resource(size_t initial_size, memory_resource *upstream);
+  monotonic_buffer_resource(void *buffer, size_t buffer_size,
+                            memory_resource *upstream);
+  monotonic_buffer_resource()
+      : monotonic_buffer_resource(get_default_resource()) {}
+  explicit monotonic_buffer_resource(size_t initial_size)
+      : monotonic_buffer_resource(initial_size, get_default_resource()) {}
+  monotonic_buffer_resource(void *buffer, size_t buffer_size)
+      : monotonic_buffer_resource(buffer, buffer_size, get_default_resource()) {}
+  monotonic_buffer_resource(const monotonic_buffer_resource&) = delete;
+  virtual ~monotonic_buffer_resource();
+  monotonic_buffer_resource
+    operator=(const monotonic_buffer_resource&) = delete;
+  void release();
+  memory_resource* upstream_resource() const;
+protected:
+  void* do_allocate(size_t bytes, size_t alignment) override;
+  void do_deallocate(void* p, size_t bytes, size_t alignment) override;
+  bool do_is_equal(const memory_resource& other) const noexcept override;
+};
+```
+#### `monotonic_buffer_resource` constructor and destructor <a id="mem.res.monotonic.buffer.ctor">[[mem.res.monotonic.buffer.ctor]]</a>
+``` cpp
+explicit monotonic_buffer_resource(memory_resource* upstream);
+monotonic_buffer_resource(size_t initial_size, memory_resource* upstream);
+```
+*Requires:* `upstream` shall be the address of a valid memory resource.
+`initial_size`, if specified, shall be greater than zero.
+*Effects:* Sets `upstream_rsrc` to `upstream` and `current_buffer` to
+`nullptr`. If `initial_size` is specified, sets `next_buffer_size` to at
+least `initial_size`; otherwise sets `next_buffer_size` to an
+*implementation-defined* size.
+``` cpp
+monotonic_buffer_resource(void* buffer, size_t buffer_size, memory_resource* upstream);
+```
+*Requires:* `upstream` shall be the address of a valid memory resource.
+`buffer_size` shall be no larger than the number of bytes in `buffer`.
+*Effects:* Sets `upstream_rsrc` to `upstream`, `current_buffer` to
+`buffer`, and `next_buffer_size` to `buffer_size` (but not less than 1),
+then increases `next_buffer_size` by an *implementation-defined* growth
+factor (which need not be integral).
+``` cpp
+~monotonic_buffer_resource();
+```
+*Effects:* Calls `release()`.
+#### `monotonic_buffer_resource` members <a id="mem.res.monotonic.buffer.mem">[[mem.res.monotonic.buffer.mem]]</a>
+``` cpp
+void release();
+```
+*Effects:* Calls `upstream_rsrc->deallocate()` as necessary to release
+all allocated memory.
+[*Note 1*: The memory is released back to `upstream_rsrc` even if some
+blocks that were allocated from `this` have not been deallocated from
+`this`. — *end note*]
+``` cpp
+memory_resource* upstream_resource() const;
+```
+*Returns:* The value of `upstream_rsrc`.
+``` cpp
+void* do_allocate(size_t bytes, size_t alignment) override;
+```
+*Returns:* A pointer to allocated storage
+([[basic.stc.dynamic.deallocation]]) with a size of at least `bytes`.
+The size and alignment of the allocated memory shall meet the
+requirements for a class derived from `memory_resource` ([[mem.res]]).
+*Effects:* If the unused space in `current_buffer` can fit a block with
+the specified `bytes` and `alignment`, then allocate the return block
+from `current_buffer`; otherwise set `current_buffer` to
+`upstream_rsrc->allocate(n, m)`, where `n` is not less than
+`max(bytes, next_buffer_size)` and `m` is not less than `alignment`, and
+increase `next_buffer_size` by an *implementation-defined* growth factor
+(which need not be integral), then allocate the return block from the
+newly-allocated `current_buffer`.
+*Throws:* Nothing unless `upstream_rsrc->allocate()` throws.
+``` cpp
+void do_deallocate(void* p, size_t bytes, size_t alignment) override;
+```
+*Effects:* None.
+*Throws:* Nothing.
+*Remarks:* Memory used by this resource increases monotonically until
+its destruction.
+``` cpp
+bool do_is_equal(const memory_resource& other) const noexcept override;
+```
+*Returns:*
+`this == dynamic_cast<const monotonic_buffer_resource*>(&other)`.

Diff to HTML by rtfpessoa