C++ Reference ยท Containers
C++ polymorphic memory resources (std::pmr)
Reference for std::pmr: memory_resource, monotonic_buffer_resource, unsynchronized and synchronized pool resources, pmr containers and arena-style allocation.
Polymorphic memory resources (C++17, headers <memory_resource> and the container headers) separate where memory comes from from the container type. A std::pmr::vector<int> always has the type vector<int, std::pmr::polymorphic_allocator<int>>; the actual source of its memory is a std::pmr::memory_resource object chosen at run time and passed to the constructor. Two containers with different resources are still the same type and can be passed to the same function.
The standard provides ready-made resources: monotonic_buffer_resource (bump allocation from a buffer, nothing is freed until the resource dies), unsynchronized_pool_resource and synchronized_pool_resource (size-class pools), plus new_delete_resource() and null_memory_resource(). Typical uses are a stack buffer for short-lived containers and an arena that is dropped all at once.
#include <memory_resource> std::byte buffer[1024]; std::pmr::monotonic_buffer_resource arena{buffer, sizeof buffer}; std::pmr::vector<int> v{&arena};
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
class memory_resource { public: void* allocate(std::size_t bytes, std::size_t alignment = alignof(std::max_align_t)); void deallocate(void* p, std::size_t bytes, std::size_t alignment = alignof(std::max_align_t)); bool is_equal(const memory_resource& other) const noexcept; private: virtual void* do_allocate(std::size_t bytes, std::size_t alignment) = 0; virtual void do_deallocate(void* p, std::size_t bytes, std::size_t alignment) = 0; virtual bool do_is_equal(const memory_resource& other) const noexcept = 0; }; memory_resource* new_delete_resource() noexcept; memory_resource* null_memory_resource() noexcept; memory_resource* get_default_resource() noexcept; memory_resource* set_default_resource(memory_resource* r) noexcept;
| Name | Description |
|---|---|
monotonic_buffer_resource(buffer, size, upstream) |
Hands out memory from the buffer in order; when it runs out, asks upstream (default: the default resource) for bigger blocks. deallocate does nothing. release() or destruction frees everything at once. |
unsynchronized_pool_resource |
Keeps free lists per block size. Not thread-safe, faster. |
synchronized_pool_resource |
Same, but safe to use from several threads. |
null_memory_resource() |
Always throws std::bad_alloc; use as upstream to forbid heap fallback. |
std::pmr::polymorphic_allocator<T> |
The allocator the pmr containers use; holds a memory_resource*. |
Returns: allocate returns suitably aligned storage or throws std::bad_alloc.
Errors / undefined behavior: destroying a resource while containers that use it are still alive, or freeing memory to a different resource than it came from, is undefined behavior.
Usage notes
- Resource outlives containers. Declare the arena (and its buffer) before the containers that use it.
- Allocator propagates to elements:
std::pmr::vector<std::pmr::string>passes its resource to the strings it constructs (uses-allocator construction). Mixingstd::pmr::vector<std::string>loses that. - Default resource: containers made without an explicit resource use
get_default_resource(), which isnew_delete_resource()unless changed. - No per-element reuse in a monotonic resource: a vector that grows repeatedly wastes the abandoned blocks until the arena is released.
reservefirst when you can. - Copy and move: a container copy constructed from another picks the default resource, not the source's; use the allocator-extended constructors (
v2(v1, &arena)) to control it. Moving between different resources copies element by element. - Cost: one virtual call per allocation, which is normally negligible compared with
malloc. - Works with
std::pmr::string,vector,deque,list,map,set,unordered_mapand more; the aliases live in each container's header.
Related
- Allocators,
std::vector,std::string, Dynamic memory - Lessons: Dynamic memory, Performance