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

Files changed (1) hide show

tmp/tmpagwmjm7n/{from.md → to.md} +148 -0

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

	@@ -0,0 +1,148 @@

+### 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