Memory
[memory]Header <experimental/memory> synopsis
[header.memory.synop]#include <memory>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
// See shared_ptr casts
[memory.smartptr.shared.cast]template<class T, class U> shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept; - Requires:
- The expression
reinterpret_cast<T*>((U*)0)shall be well formed. - Returns:
shared_ptr<T>(r, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get())).
Type-erased allocator
[memory.type.erased.allocator]
A type-erased allocator is an allocator or memory resource, alloc,
used to allocate internal data structures for an object X of type C,
but where C is not dependent on the type of alloc.
Once alloc has been supplied to X (typically as a constructor argument),
alloc can be retrieved from X only as a pointer rptr of static type std::experimental::pmr::memory_resource* (rptr is computed from alloc depends on the type of alloc as described in
If the type of alloc is |
then the value of rptr is |
|---|---|
non-existent — no alloc specified |
The value of experimental::pmr::get_default_resource() at the time of construction. |
nullptr_t |
The value of experimental::pmr::get_default_resource() at the time of construction. |
a pointer type convertible to pmr::memory_resource* |
static_cast<experimental::pmr::memory_resource*>(alloc) |
pmr::polymorphic_allocator<U> |
alloc.resource() |
| any other type meeting the Allocator requirements ( |
a pointer to a value of type experimental::pmr::resource_adaptor<A> where A is the type of alloc.
rptr remains valid only for the lifetime of X. |
| None of the above | The program is ill-formed. |
Additionally, class C shall meet the following requirements:
C::allocator_typeshall be identical tostd::experimental::erased_type.X.get_memory_resource()returnsrptr.
Header <experimental/memory_resource> synopsis
[memory.resource.synop]namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
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;
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;
// The name resource_adaptor_imp is for exposition only.
template <class Allocator> class resource_adaptor_imp;
template <class Allocator>
using resource_adaptor = resource_adaptor_imp<
allocator_traits<Allocator>::rebind_alloc<char>>;
// Global memory resources
memory_resource* new_delete_resource() noexcept;
memory_resource* null_memory_resource() noexcept;
// The default memory resource
memory_resource* set_default_resource(memory_resource* r) noexcept;
memory_resource* get_default_resource() noexcept;
// Standard memory resources
struct pool_options;
class synchronized_pool_resource;
class unsynchronized_pool_resource;
class monotonic_buffer_resource;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdClass memory_resource
[memory.resource]Class memory_resource overview
[memory.resource.overview]
The memory_resource class is an abstract interface to an unbounded set of classes encapsulating memory resources.
class memory_resource {
// For exposition only
static constexpr size_t max_align = alignof(max_align_t);
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;
protected:
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
[memory.resource.public]~memory_resource(); - Effects:
- Destroys this memory_resource.
void* allocate(size_t bytes, size_t alignment = max_align); - Effects:
- Equivalent to
return do_allocate(bytes, alignment);
void deallocate(void* p, size_t bytes, size_t alignment = max_align); - Effects:
- Equivalent to
do_deallocate(p, bytes, alignment);
bool is_equal(const memory_resource& other) const noexcept; - Effects:
- Equivalent to
return do_is_equal(other);
memory_resource protected virtual member functions
[memory.resource.priv]virtual void* do_allocate(size_t bytes, size_t alignment) = 0; - Preconditions:
- alignment shall be a power of two.
- Returns:
- A derived class shall implement this function to return a pointer to allocated storage (
C++14 §3.7.4.2 bytes. The returned storage is aligned to the specified alignment, if such alignment is supported; otherwise it is aligned tomax_align. - Throws:
- a derived class implementation shall throw an appropriate exception if it is unable to allocate memory with the requested size and alignment.
virtual void do_deallocate(void* p, size_t bytes, size_t alignment) = 0; - Preconditions:
pshall have been returned from a prior call toallocate(bytes, alignment)on a memory resource equal to*this, and the storage atpshall not yet have been deallocated.- Effects:
- A derived class shall implement this function to dispose of allocated storage.
- Throws:
- Nothing.
virtual bool do_is_equal(const memory_resource& other) const noexcept = 0; - Returns:
- A derived class shall implement this function to return
trueif memory allocated from this can be deallocated from other and vice-versa; otherwise it shall return false.[ Note: 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 compute dynamic_cast<const D*>(&other)and go no further (i.e., returnfalse) if it returnsnullptr. — end note ]
memory_resource equality
[memory.resource.eq]bool operator==(const memory_resource& a, const memory_resource& b) noexcept; - Returns:
&a == &b || a.is_equal(b).
bool operator!=(const memory_resource& a, const memory_resource& b) noexcept; - Returns:
!(a == b).
Class template polymorphic_allocator
[memory.polymorphic.allocator.class]Class template polymorphic_allocator overview
[memory.polymorphic.allocator.overview]
A specialization of class template pmr::polymorphic_allocator conforms to the Allocator requirements (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.
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class Tp>
class polymorphic_allocator {
memory_resource* m_resource; // For exposition only
public:
typedef Tp value_type;
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) = default;
Tp* allocate(size_t n);
void deallocate(Tp* p, size_t n);
template <class T, class... Args>
void construct(T* p, Args&&... args);
// Specializations for pair using piecewise construction
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 std::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);
// Return a default-constructed allocator (no allocator propagation)
polymorphic_allocator select_on_container_copy_construction() const;
memory_resource* resource() const;
};
} // namespace pmr
} // namespace experimental
} // namespace stdpolymorphic_allocator constructors
[memory.polymorphic.allocator.ctor]polymorphic_allocator() noexcept; - Effects:
- Sets
m_resourcetoget_default_resource().
polymorphic_allocator(memory_resource* r); - Preconditions:
ris non-null.- Effects:
- Sets
m_resourcetor. - Throws:
- nothing
- Notes:
- This constructor provides an implicit conversion from
memory_resource*.
template <class U>
polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept; - Effects:
- sets
m_resourcetoother.resource().
polymorphic_allocator member functions
[memory.polymorphic.allocator.mem]Tp* allocate(size_t n); - Returns:
- Equivalent to
static_cast<Tp*>(m_resource->allocate(n * sizeof(Tp), alignof(Tp))).
void deallocate(Tp* p, size_t n); - Preconditions:
pwas allocated from a memory resource,x, equal to*m_resource, usingx.allocate(n * sizeof(Tp), alignof(Tp)).- Effects:
- Equivalent to
m_resource->deallocate(p, n * sizeof(Tp), alignof(Tp)). - Throws:
- Nothing.
template <class T, class... Args>
void construct(T* p, Args&&... args); - Requires:
Uses-allocator construction ofTwith allocatorthis->resource()(see2.1 std::forward<Args>(args)...is well-formed.[ Note: uses-allocator construction is always well formed for types that do not use allocators. — end note ]- Effects:
- Construct a
Tobject atpbyuses-allocator construction with allocatorthis->resource()(2.1 std::forward<Args>(args).... - Throws:
- : Nothing unless the constructor for
Tthrows.
template <class T1, class T2, class... Args1, class... Args2>
void construct(pair<T1,T2>* p, piecewise_construct_t,
tuple<Args1...> x, tuple<Args2...> y); - Effects:
-
Let
xprimebe atupleconstructed fromxaccording to the appropriate rule from the following list.[ Note: The following description can be summarized as constructing a std::pair<T1,T2>object atpas if by separate uses-allocator construction with allocatorthis->resource()(2.1 p->firstusing the elements ofxandp->secondusing the elements ofy. — end note ]- If
uses_allocator<T1,memory_resource*>::valueisfalseandis_constructible<T,Args1...>::valueistrue, thenxprimeisx. - Otherwise, if
uses_allocator<T1,memory_resource*>::valueistrueandis_constructible<T1,allocator_arg_t,memory_resource*,Args1...>::valueistrue, thenxprimeistuple_cat(make_tuple(allocator_arg, this->resource()), std::move(x)). - Otherwise, if
uses_allocator<T1,memory_resource*>::valueistrueandis_constructible<T1,Args1...,memory_resource*>::valueistrue, thenxprimeistuple_cat(std::move(x), make_tuple(this->resource())). - Otherwise the program is ill formed.
- If
uses_allocator<T2,memory_resource*>::valueisfalseandis_constructible<T,Args2...>::valueistrue, thenyprimeisy. - Otherwise, if
uses_allocator<T2,memory_resource*>::valueistrueandis_constructible<T2,allocator_arg_t,memory_resource*,Args2...>::valueistrue, thenyprimeistuple_cat(make_tuple(allocator_arg, this->resource()), std::move(y)). - Otherwise, if
uses_allocator<T2,memory_resource*>::valueistrueandis_constructible<T2,Args2...,memory_resource*>::valueistrue, thenyprimeistuple_cat(std::move(y), make_tuple(this->resource())). - Otherwise the program is ill formed.
std::pair<T1,T2>object atpusing constructor argumentspiecewise_construct, xprime, yprime. - If
template <class T1, class T2>
void construct(std::pair<T1,T2>* p); - Effects:
- Equivalent to
this->construct(p, piecewise_construct, tuple<>(), tuple<>());
template <class T1, class T2, class U, class V>
void construct(std::pair<T1,T2>* p, U&& x, V&& y); - Effects:
- Equivalent to
this->construct(p, piecewise_construct, forward_as_tuple(std::forward<U>(x)), forward_as_tuple(std::forward<V>(y)));
template <class T1, class T2, class U, class V>
void construct(std::pair<T1,T2>* p, const std::pair<U, V>& pr); - Effects:
- Equivalent to
this->construct(p, piecewise_construct, forward_as_tuple(pr.first), forward_as_tuple(pr.second));
template <class T1, class T2, class U, class V>
void construct(std::pair<T1,T2>* p, std::pair<U, V>&& pr); - Effects:
- Equivalent to
this->construct(p, piecewise_construct, forward_as_tuple(std::forward<U>(pr.first)), forward_as_tuple(std::forward<V>(pr.second)));
template <class T>
void destroy(T* p); - Effects:
p->~T().
polymorphic_allocator select_on_container_copy_construction() const; - Returns:
polymorphic_allocator().
memory_resource* resource() const; - Returns:
- m_resource.
polymorphic_allocator equality
[memory.polymorphic.allocator.eq]template <class T1, class T2>
bool operator==(const polymorphic_allocator<T1>& a,
const polymorphic_allocator<T2>& b) noexcept; - Returns:
*a.resource() == *b.resource().
template <class T1, class T2>
bool operator!=(const polymorphic_allocator<T1>& a,
const polymorphic_allocator<T2>& b) noexcept; - Returns:
! (a == b)
template alias resource_adaptor
[memory.resource.adaptor]resource_adaptor
[memory.resource.adaptor.overview]
An instance of resource_adaptor<Allocator> is an adaptor that wraps a memory_resource interface around Allocator.
In order that resource_adaptor<X<T>> and resource_adaptor<X<U>> are the same type for any allocator template X and types T and U,
resource_adaptor<Allocator> is rendered as an alias to a class template such that Allocator is rebound to a char value type in every specialization of the class template.
The requirements on this class template are defined below.
The name resource_adaptor_imp is for exposition only and is not normative,
but the definitions of the members of that class, whatever its name, are normative.
In addition to the Allocator requirements (resource_adaptor shall meet the following additional requirements:
typename allocator_traits<Allocator>::pointershall be identical totypename allocator_traits<Allocator>::value_type*.typename allocator_traits<Allocator>::const_pointershall be identical totypename allocator_traits<Allocator>::value_type const*.typename allocator_traits<Allocator>::void_pointershall be identical tovoid*.typename allocator_traits<Allocator>::const_void_pointershall be identical tovoid const*.
// The name resource_adaptor_imp is for exposition only.
template <class Allocator>
class resource_adaptor_imp : public memory_resource {
// for exposition only
Allocator m_alloc;
public:
typedef Allocator allocator_type;
resource_adaptor_imp() = default;
resource_adaptor_imp(const resource_adaptor_imp&) = default;
resource_adaptor_imp(resource_adaptor_imp&&) = default;
explicit resource_adaptor_imp(const Allocator& a2);
explicit resource_adaptor_imp(Allocator&& a2);
resource_adaptor_imp& operator=(const resource_adaptor_imp&) = default;
allocator_type get_allocator() const { return m_alloc; }
protected:
virtual void* do_allocate(size_t bytes, size_t alignment);
virtual void do_deallocate(void* p, size_t bytes, size_t alignment);
virtual bool do_is_equal(const memory_resource& other) const noexcept;
};
template <class Allocator>
using resource_adaptor = typename resource_adaptor_imp<
allocator_traits<Allocator>::template rebind_alloc<char>>;resource_adaptor_imp constructors
[memory.resource.adaptor.ctor]explicit resource_adaptor_imp(const Allocator& a2); - Effects:
- Initializes
m_allocwitha2.
explicit resource_adaptor_imp(Allocator&& a2); - Effects:
- Initializes
m_allocwithstd::move(a2).
resource_adaptor_imp member functions
[memory.resource.adaptor.mem]void* do_allocate(size_t bytes, size_t alignment); - Returns:
- Allocated memory obtained by calling
m_alloc.allocate. The size and alignment of the allocated memory shall meet the requirements for a class derived frommemory_resource(8.5
void do_deallocate(void* p, size_t bytes, size_t alignment); - Requires:
pwas previously allocated usingA.allocate, whereA == m_alloc, and not subsequently deallocated.- Effects:
- Returns memory to the allocator using
m_alloc.deallocate().
bool do_is_equal(const memory_resource& other) const noexcept; - Returns:
falseifpis null, otherwise the value ofm_alloc == p->m_alloc.
Let p be dynamic_cast<const resource_adaptor_imp*>(&other).
Access to program-wide memory_resource objects
[memory.resource.global]memory_resource* new_delete_resource() noexcept; - Returns:
- A pointer to a static-duration object of a type derived from
memory_resourcethat can serve as a resource for allocating memory using::operator newand::operator delete. The same value is returned every time this function is called. For return valuepand memory resourcer,p->is_equal(r)returns&r == p.
memory_resource* null_memory_resource() noexcept; - Returns:
-
A pointer to a static-duration object of a type derived from
memory_resourcefor whichallocate()always throwsbad_allocand for whichdeallocate()has no effect. The same value is returned every time this function is called. For return valuepand memory resourcer,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().
memory_resource* set_default_resource(memory_resource* r) noexcept; - Effects:
-
If
ris non-null, sets the value of the default memory resource pointer tor, otherwise sets the default memory resource pointer tonew_delete_resource(). - Postconditions:
get_default_resource() == r.- Returns:
- The previous value of the default memory resource pointer.
- Remarks:
-
Calling the
set_default_resourceandget_default_resourcefunctions shall not incur a data race. A call to theset_default_resourcefunction shall synchronize with subsequent calls to theset_default_resourceandget_default_resourcefunctions.
memory_resource* get_default_resource() noexcept; - Returns:
- The current value of the default memory resource pointer.
Pool resource classes
[memory.resource.pool]Classes synchronized_pool_resource and unsynchronized_pool_resource
[memory.resource.pool.overview]
The synchronized_pool_resource and unsynchronized_pool_resource classes (collectively, pool resource classes)
are general-purpose memory resources having the following qualities:
- Each resource
owns the allocated memory, and frees it on destruction – even ifdeallocatehas not been called for some of the allocated blocks. - A pool resource (see
Figure 1 do_allocate. Each call todo_allocate(size, alignment)is dispatched to the pool serving the smallest blocks accommodating at leastsizebytes. - 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: 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_optionsstruct 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.
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:
virtual void* do_allocate(size_t bytes, size_t alignment);
virtual void do_deallocate(void* p, size_t bytes, size_t alignment);
virtual bool do_is_equal(const memory_resource& other) const noexcept;
};
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:
virtual void* do_allocate(size_t bytes, size_t alignment);
virtual void do_deallocate(void* p, size_t bytes, size_t alignment);
virtual bool do_is_equal(const memory_resource& other) const noexcept;
};pool_options data members
[memory.resource.pool.options]
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:
size_t max_blocks_per_chunk;
The maximum number of blocks that will be allocated at once from the upstream memory resource 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.
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
[memory.resource.pool.ctor]synchronized_pool_resource(const pool_options& opts, memory_resource* upstream); unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream); - Preconditions:
upstreamis the address of a valid memory resource.- Effects:
-
Constructs a pool resource object that will obtain memory from
upstreamwhenever the pool resource is unable to satisfy a memory request from its own internal data structures. The resulting object will hold a copy ofupstream, but will not own the resource to whichupstreampoints.[ Note: The intention is that calls to The behavior of the pooling mechanism is tuned according to the value of the opts argument.upstream->allocate()will be substantially fewer than calls tothis->allocate()in most cases. — end note ] - Throws:
- Nothing unless
upstream->allocate()throws. It is unspecified if or under what conditions this constructor callsupstream->allocate().
virtual ~synchronized_pool_resource(); virtual ~unsynchronized_pool_resource(); - Effects:
- calls
this->release().
pool resource members
[memory.resource.pool.mem]void release(); - Effects:
-
Calls
upstream_resource()->deallocate()as necessary to release all allocated memory.[ Note: memory is released back to upstream_resource()even ifdeallocatehas not been called for some of the allocated blocks. — end note ]
memory_resource* upstream_resource() const; - Returns:
- The value of the
upstreamargument provided to the constructor of this object.
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.
virtual void* do_allocate(size_t bytes, size_t alignment); - Returns:
- A pointer to allocated storage (
C++14 §3.7.4.2 bytes. The size and alignment of the allocated memory shall meet the requirements for a class derived frommemory_resource(8.5 - Effects:
-
If the pool selected for a block of size
bytesis unable to satisfy the memory request from its own internal data structures, it will callupstream_resource()->allocate()to obtain more memory. Ifbytesis larger than that which the largest pool can handle, then memory will be allocated usingupstream_resource()->allocate(). - Throws:
- Nothing unless
upstream_resource()->allocate()throws.
virtual void do_deallocate(void* p, size_t bytes, size_t alignment); - Effects:
- Return the memory at
pto the pool. It is unspecified if or under what circumstances this operation will result in a call toupstream_resource()->deallocate(). - Throws:
- Nothing
virtual bool unsynchronized_pool_resource::do_is_equal(const memory_resource& other) const noexcept; - Returns:
this == dynamic_cast<const unsynchronized_pool_resource*>(&other).
virtual bool synchronized_pool_resource::do_is_equal(const memory_resource& other) const noexcept; - Returns:
this == dynamic_cast<const synchronized_pool_resource*>(&other).
Class monotonic_buffer_resource
[memory.resource.monotonic.buffer]Class monotonic_buffer_resource overview
[memory.resource.monotonic.buffer.overview]
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
deallocatehas 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
allocateanddeallocatedo not synchronize with one another. - It
owns the allocated memory and frees it on destruction, even ifdeallocatehas not been called for some of the allocated blocks.
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:
virtual void* do_allocate(size_t bytes, size_t alignment);
virtual void do_deallocate(void* p, size_t bytes,
size_t alignment);
virtual bool do_is_equal(const memory_resource& other) const noexcept;
};monotonic_buffer_resource constructor and destructor
[memory.resource.monotonic.buffer.ctor]explicit monotonic_buffer_resource(memory_resource* upstream); monotonic_buffer_resource(size_t initial_size, memory_resource* upstream); - Preconditions:
upstreamshall be the address of a valid memory resource.initial_size, if specified, shall be greater than zero.- Effects:
- Sets
upstream_rsrctoupstreamandcurrent_buffertonullptr. Ifinitial_sizeis specified, setsnext_buffer_sizeto at leastinitial_size; otherwise setsnext_buffer_sizeto an implementation-defined size.
monotonic_buffer_resource(void* buffer, size_t buffer_size, memory_resource* upstream); - Preconditions:
upstreamshall be the address of a valid memory resource.buffer_sizeshall be no larger than the number of bytes inbuffer.- Effects:
- Sets
upstream_rsrctoupstream,current_buffertobuffer, andnext_buffer_sizetoinitial_size(but not less than 1), then increasesnext_buffer_sizeby an implementation-defined growth factor (which need not be integral).
~monotonic_buffer_resource(); - Effects:
- Calls
this->release().
monotonic_buffer_resource members
[memory.resource.monotonic.buffer.mem]void release(); - Effects:
- Calls
upstream_rsrc->deallocate()as necessary to release all allocated memory.
upstream_rsrc even if some blocks that were allocated from this have not been deallocated from this.
— end note ]
memory_resource* upstream_resource() const; - Returns:
- the value of
upstream_rsrc.
void* do_allocate(size_t bytes, size_t alignment); - Returns:
- A pointer to allocated storage (
C++14 §3.7.4.2 bytes. The size and alignment of the allocated memory shall meet the requirements for a class derived frommemory_resource(8.5 - Effects:
-
If the unused space in
current_buffercan fit a block with the specifiedbytesandalignment, then allocate the return block fromcurrent_buffer; otherwise setcurrent_buffertoupstream_rsrc->allocate(n, m), wherenis not less thanmax(bytes, next_buffer_size)andmis not less thanalignment, and increasenext_buffer_sizeby an implementation-defined growth factor (which need not be integral), then allocate the return block from the newly-allocatedcurrent_buffer. - Throws:
- Nothing unless
upstream_rsrc->allocate()throws.
void do_deallocate(void* p, size_t bytes, size_t alignment); - Effects:
- None
- Throws:
- Nothing
- Remarks:
- Memory used by this resource increases monotonically until its destruction.
bool do_is_equal(const memory_resource& other) const noexcept; - Returns:
this == dynamic_cast<const monotonic_buffer_resource*>(&other).
Alias templates using polymorphic memory resources
[memory.resource.aliases]Header <experimental/string> synopsis
[header.string.synop]#include <string>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
// basic_string using polymorphic allocator in namespace pmr
template <class charT, class traits = char_traits<charT>>
using basic_string =
std::basic_string<charT, traits, polymorphic_allocator<charT>>;
// basic_string typedef names using polymorphic allocator in namespace
// std::experimental::pmr
typedef basic_string<char> string;
typedef basic_string<char16_t> u16string;
typedef basic_string<char32_t> u32string;
typedef basic_string<wchar_t> wstring;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/deque> synopsis
[header.deque.synop]#include <deque>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class T>
using deque = std::deque<T,polymorphic_allocator<T>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/forward_list> synopsis
[header.forward_list.synop]#include <forward_list>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class T>
using forward_list =
std::forward_list<T,polymorphic_allocator<T>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/list> synopsis
[header.list.synop]#include <list>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class T>
using list = std::list<T,polymorphic_allocator<T>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/vector> synopsis
[header.vector.synop]#include <vector>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class T>
using vector = std::vector<T,polymorphic_allocator<T>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/map> synopsis
[header.map.synop]#include <map>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class Key, class T, class Compare = less<Key>>
using map = std::map<Key, T, Compare,
polymorphic_allocator<pair<const Key,T>>>;
template <class Key, class T, class Compare = less<Key>>
using multimap = std::multimap<Key, T, Compare,
polymorphic_allocator<pair<const Key,T>>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/set> synopsis
[header.set.synop]#include <set>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class Key, class Compare = less<Key>>
using set = std::set<Key, Compare,
polymorphic_allocator<Key>>;
template <class Key, class Compare = less<Key>>
using multiset = std::multiset<Key, Compare,
polymorphic_allocator<Key>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/unordered_map> synopsis
[header.unordered_map.synop]#include <unordered_map>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class Key, class T,
class Hash = hash<Key>,
class Pred = equal_to<Key>>
using unordered_map =
std::unordered_map<Key, T, Hash, Pred,
polymorphic_allocator<pair<const Key,T>>>;
template <class Key, class T,
class Hash = hash<Key>,
class Pred = equal_to<Key>>
using unordered_multimap =
std::unordered_multimap<Key, T, Hash, Pred,
polymorphic_allocator<pair<const Key,T>>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/unordered_set> synopsis
[header.unordered_set.synop]#include <unordered_set>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class Key,
class Hash = hash<Key>,
class Pred = equal_to<Key>>
using unordered_set = std::unordered_set<Key, Hash, Pred,
polymorphic_allocator<Key>>;
template <class Key,
class Hash = hash<Key>,
class Pred = equal_to<Key>>
using unordered_multiset =
std::unordered_multiset<Key, Hash, Pred,
polymorphic_allocator<Key>>;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace stdHeader <experimental/regex> synopsis
[header.regex.synop]#include <regex>
#include <exerimental/string>
namespace std {
namespace experimental {
inline namespace fundamentals_v1 {
namespace pmr {
template <class BidirectionalIterator>
using match_results =
std::match_results<BidirectionalIterator,
polymorphic_allocator<sub_match<BidirectionalIterator>>>;
typedef match_results<const char*> cmatch;
typedef match_results<const wchar_t*> wcmatch;
typedef match_results<string::const_iterator> smatch;
typedef match_results<wstring::const_iterator> wsmatch;
} // namespace pmr
} // namespace fundamentals_v1
} // namespace experimental
} // namespace std