[mem.res] - C++20 → C++23

Files changed (1) hide show

tmp/tmpcgl3k0rk/{from.md → to.md} +46 -49

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

@@ -8,11 +8,11 @@ namespace std::pmr {
   class memory_resource;
   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;
@@ -30,10 +30,12 @@ namespace std::pmr {
 }
 ```
 ### 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
 namespace std::pmr {
@@ -71,11 +73,17 @@ namespace std::pmr {
 ``` cpp
 [[nodiscard]] 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);
 ```
@@ -122,13 +130,13 @@ 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`, an implementation of this function
-could immediately return `false` if
 `dynamic_cast<const D*>(&other) == nullptr`. — *end note*]
 #### Equality <a id="mem.res.eq">[[mem.res.eq]]</a>
 ``` cpp
@@ -137,22 +145,26 @@ bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
 *Returns:* `&a == &b || a.is_equal(b)`.
 ### Class template `polymorphic_allocator` <a id="mem.poly.allocator.class">[[mem.poly.allocator.class]]</a>
 A specialization of class template `pmr::polymorphic_allocator` meets
-the *Cpp17Allocator* requirements ([[cpp17.allocator]]). 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.
-All specializations of class template `pmr::polymorphic_allocator` meet
 the allocator completeness requirements
-[[allocator.requirements.completeness]].
 ``` cpp
 namespace std::pmr {
   template<class Tp = byte> class polymorphic_allocator {
     memory_resource* memory_rsrc;       // exposition only
@@ -183,16 +195,19 @@ namespace std::pmr {
     template<class T> void delete_object(T* p);
     template<class T, class... Args>
       void construct(T* p, Args&&... args);
-    template<class T>
-      void destroy(T* p);
     polymorphic_allocator select_on_container_copy_construction() const;
     memory_resource* resource() const;
   };
 }
 ```
 #### Constructors <a id="mem.poly.allocator.ctor">[[mem.poly.allocator.ctor]]</a>
@@ -290,11 +305,11 @@ template<class T>
 ```
 *Effects:* Equivalent to `deallocate_bytes(p, n*sizeof(T), alignof(T))`.
 ``` cpp
-template<class T, class CtorArgs...>
   [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
 ```
 *Effects:* Allocates and constructs an object of type `T`, as follows.
 Equivalent to:
@@ -319,11 +334,11 @@ template<class T>
 ```
 *Effects:* Equivalent to:
 ``` cpp
-destroy(p);
 deallocate_object(p);
 ```
 ``` cpp
 template<class T, class... Args>
@@ -338,17 +353,10 @@ template<class T, class... Args>
 represented by `p` by uses-allocator construction with allocator `*this`
 and constructor arguments `std::forward<Args>(args)...`.
 *Throws:* Nothing unless the constructor for `T` throws.
-``` 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()`.
@@ -611,22 +619,22 @@ rounded to unspecified granularity.
 ``` cpp
 void* do_allocate(size_t bytes, size_t alignment) override;
 ```
-*Returns:* A pointer to allocated
-storage [[basic.stc.dynamic.allocation]] 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.class]].
 *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;
 ```
@@ -643,28 +651,16 @@ bool do_is_equal(const memory_resource& other) const noexcept override;
 *Returns:* `this == &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
 namespace std::pmr {
   class monotonic_buffer_resource : public memory_resource {
     memory_resource* upstream_rsrc;     // exposition only
@@ -739,11 +735,12 @@ factor (which need not be integral).
 ``` 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*]
@@ -755,25 +752,25 @@ memory_resource* upstream_resource() const;
 ``` cpp
 void* do_allocate(size_t bytes, size_t alignment) override;
 ```
-*Returns:* A pointer to allocated
-storage [[basic.stc.dynamic.allocation]] 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.class]].
 *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;
 ```

   class memory_resource;
   bool operator==(const memory_resource& a, const memory_resource& b) noexcept;
   // [mem.poly.allocator.class], class template polymorphic_allocator
+  template<class Tp = byte> class polymorphic_allocator;
   template<class T1, class T2>
     bool operator==(const polymorphic_allocator<T1>& a,
                     const polymorphic_allocator<T2>& b) noexcept;
 }
 ```
 ### Class `memory_resource` <a id="mem.res.class">[[mem.res.class]]</a>
+#### General <a id="mem.res.class.general">[[mem.res.class.general]]</a>
 The `memory_resource` class is an abstract interface to an unbounded set
 of classes encapsulating memory resources.
 ``` cpp
 namespace std::pmr {
 ``` cpp
 [[nodiscard]] void* allocate(size_t bytes, size_t alignment = max_align);
 ```
+*Effects:* Allocates storage by calling `do_allocate(bytes, alignment)`
+and implicitly creates objects within the allocated region of storage.
+*Returns:* A pointer to a suitable created object [[intro.object]] in
+the allocated region of storage.
+*Throws:* What and when the call to `do_allocate` throws.
 ``` cpp
 void deallocate(void* p, size_t bytes, size_t alignment = max_align);
 ```
 *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*: It is possible that the most-derived type of `other` does
+not match the type of `this`. For a derived class `D`, an implementation
+of this function can immediately return `false` if
 `dynamic_cast<const D*>(&other) == nullptr`. — *end note*]
 #### Equality <a id="mem.res.eq">[[mem.res.eq]]</a>
 ``` cpp
 *Returns:* `&a == &b || a.is_equal(b)`.
 ### Class template `polymorphic_allocator` <a id="mem.poly.allocator.class">[[mem.poly.allocator.class]]</a>
+#### General <a id="mem.poly.allocator.class.general">[[mem.poly.allocator.class.general]]</a>
 A specialization of class template `pmr::polymorphic_allocator` meets
+the *Cpp17Allocator* requirements [[allocator.requirements.general]] if
+its template argument is a cv-unqualified object type. 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.
+A specialization of class template `pmr::polymorphic_allocator` meets
 the allocator completeness requirements
+[[allocator.requirements.completeness]] if its template argument is a
+cv-unqualified object type.
 ``` cpp
 namespace std::pmr {
   template<class Tp = byte> class polymorphic_allocator {
     memory_resource* memory_rsrc;       // exposition only
     template<class T> void delete_object(T* p);
     template<class T, class... Args>
       void construct(T* p, Args&&... args);
     polymorphic_allocator select_on_container_copy_construction() const;
     memory_resource* resource() const;
+    // friends
+    friend bool operator==(const polymorphic_allocator& a,
+                           const polymorphic_allocator& b) noexcept {
+      return *a.resource() == *b.resource();
+    }
   };
 }
 ```
 #### Constructors <a id="mem.poly.allocator.ctor">[[mem.poly.allocator.ctor]]</a>
 ```
 *Effects:* Equivalent to `deallocate_bytes(p, n*sizeof(T), alignof(T))`.
 ``` cpp
+template<class T, class... CtorArgs>
   [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
 ```
 *Effects:* Allocates and constructs an object of type `T`, as follows.
 Equivalent to:
 ```
 *Effects:* Equivalent to:
 ``` cpp
+allocator_traits<polymorphic_allocator>::destroy(*this, p);
 deallocate_object(p);
 ```
 ``` cpp
 template<class T, class... Args>
 represented by `p` by uses-allocator construction with allocator `*this`
 and constructor arguments `std::forward<Args>(args)...`.
 *Throws:* Nothing unless the constructor for `T` throws.
 ``` cpp
 polymorphic_allocator select_on_container_copy_construction() const;
 ```
 *Returns:* `polymorphic_allocator()`.
 ``` cpp
 void* do_allocate(size_t bytes, size_t alignment) override;
 ```
 *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()`.
+*Returns:* A pointer to allocated
+storage [[basic.stc.dynamic.allocation]] 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.class]].
 *Throws:* Nothing unless `upstream_resource()->allocate()` throws.
 ``` cpp
 void do_deallocate(void* p, size_t bytes, size_t alignment) override;
 ```
 *Returns:* `this == &other`.
 ### Class `monotonic_buffer_resource` <a id="mem.res.monotonic.buffer">[[mem.res.monotonic.buffer]]</a>
+#### General <a id="mem.res.monotonic.buffer.general">[[mem.res.monotonic.buffer.general]]</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.
 ``` cpp
 namespace std::pmr {
   class monotonic_buffer_resource : public memory_resource {
     memory_resource* upstream_rsrc;     // exposition only
 ``` cpp
 void release();
 ```
 *Effects:* Calls `upstream_rsrc->deallocate()` as necessary to release
+all allocated memory. Resets `current_buffer` and `next_buffer_size` to
+their initial values at construction.
 [*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
 void* do_allocate(size_t bytes, size_t alignment) override;
 ```
 *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`.
+*Returns:* A pointer to allocated
+storage [[basic.stc.dynamic.allocation]] 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.class]].
 *Throws:* Nothing unless `upstream_rsrc->allocate()` throws.
 ``` cpp
 void do_deallocate(void* p, size_t bytes, size_t alignment) override;
 ```

Diff to HTML by rtfpessoa