Skip to content
Tutorials Center
My learning

Topics

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.

C++
#include <memory_resource>

std::byte buffer[1024];
std::pmr::monotonic_buffer_resource arena{buffer, sizeof buffer};
std::pmr::vector<int> v{&arena};

Try it

C++ Containers on a stack buffer

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.

C++ A resource that reports what it does

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

C++
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). Mixing std::pmr::vector<std::string> loses that.
  • Default resource: containers made without an explicit resource use get_default_resource(), which is new_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. reserve first 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_map and more; the aliases live in each container's header.