C++ named requirements: Allocator

Encapsulates strategies for access/addressing, allocation/deallocation and construction/destruction of objects.

Every standard library component that may need to allocate or release storage, from std::string, std::vector, and every container, except std::array(since C++11) and std::inplace_vector(since C++26), to std::shared_ptr and std::function (until C++17) , does so through an Allocator

The implementation of many allocator requirements is optional because all AllocatorAwareContainer access allocators indirectly through std::allocator_traits, and std::allocator_traits

Requirements

Given

• T, a non-const, non-reference type(until C++11) non-const object type(since C++11)(until C++17) cv-unqualified object type(since C++17)
• A, an Allocator type for type T,
• a, an object of type A,
• B, the corresponding Allocator type for some cv-unqualified object type U (as obtained by rebinding A),
• b, an object of type B,
• p, a value of type std::allocator_traits <A> :: pointer , obtained by calling std::allocator_traits <A> :: allocate ( )
• cp, a value of type std::allocator_traits <A> :: const_pointer , obtained by conversion from p
• vp, a value of type std::allocator_traits <A> :: void_pointer , obtained by conversion from p
• cvp, a value of type std::allocator_traits <A> :: const_void_pointer , obtained by conversion from cp or from vp
• xp, a dereferenceable pointer to some cv-unqualified object type X,
• r, an lvalue of type T obtained by the expression *p,
• n, a value of type std::allocator_traits <A> :: size_type

Notes:

1. ↑ See also fancy pointers below.
2. ↑ rebind is only optional (provided by std::allocator_traits) if this allocator is a template of the form SomeAllocator<T, Args>, where Args

Given

• x1 and x2, objects of (possibly different) types X::void_pointer, X::const_void_pointer, X::pointer, or X::const_pointer

Then, x1 and x2 are equivalently-valued pointer values, if and only if both x1 and x2 can be explicitly converted to the two corresponding objects px1 and px2 of type X::const_pointer, using a sequence of static_casts using only these four types, and the expression px1 == px2 evaluates to true

Given

• w1 and w2, objects of type X::void_pointer

Then, for the expression w1 == w2 and w1 != w2 either or both objects may be replaced by an equivalently-valued object of type X::const_void_pointer

Given

• p1 and p2, objects of type X::pointer

Then, for the expressions p1 == p2, p1 != p2, p1 < p2, p1 <= p2, p1 >= p2, p1 > p2, p1 - p2 either or both objects may be replaced by an equivalently-valued object of type X::const_pointer

The above requirements make it possible to compare Container's iterators and const_iterator

Stateful and stateless allocators

Every Allocator type is either stateful or stateless

Instances of a stateless allocator type always compare equal. Stateless allocator types are typically implemented as empty classes and suitable for empty base class optimization.

Fancy pointers

When the member type pointer is not a raw pointer type, it is commonly referred to as a "fancy pointer" boost::interprocess::offset_ptr, which makes it possible to allocate node-based data structures such as std::set in shared memory and memory mapped files mapped in different addresses in every process. Fancy pointers can be used independently of the allocator that provided them , through the class template std::pointer_traits (since C++11) . The function std::to_address can be used to obtain a raw pointer from a fancy pointer.(since C++20)

Standard library

The following standard library components satisfy the Allocator requirements:

Examples

#include <cstdlib>
#include <iostream>
#include <limits>
#include <new>
#include <vector>
 
template<class T>
struct Mallocator
{
    typedef T value_type;
 
    Mallocator() = default;
 
    template<class U>
    constexpr Mallocator(const Mallocator <U>&) noexcept {}
 
    [[nodiscard]] T* allocate(std::size_t n)
    {
        if (n > std::numeric_limits<std::size_t>::max() / sizeof(T))
            throw std::bad_array_new_length();
 
        if (auto p = static_cast<T*>(std::malloc(n * sizeof(T))))
        {
            report(p, n);
            return p;
        }
 
        throw std::bad_alloc();
    }
 
    void deallocate(T* p, std::size_t n) noexcept
    {
        report(p, n, 0);
        std::free(p);
    }
private:
    void report(T* p, std::size_t n, bool alloc = true) const
    {
        std::cout << (alloc ? "Alloc: " : "Dealloc: ") << sizeof(T) * n
                  << " bytes at " << std::hex << std::showbase
                  << reinterpret_cast<void*>(p) << std::dec << '\n';
    }
};
 
template<class T, class U>
bool operator==(const Mallocator <T>&, const Mallocator <U>&) { return true; }
 
template<class T, class U>
bool operator!=(const Mallocator <T>&, const Mallocator <U>&) { return false; }
 
int main()
{
    std::vector<int, Mallocator<int>> v(8);
    v.push_back(42);
}

Alloc: 32 bytes at 0x2020c20
Alloc: 64 bytes at 0x2023c60
Dealloc: 32 bytes at 0x2020c20
Dealloc: 64 bytes at 0x2023c60

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

1. ↑ The member types reference and const_reference of std::allocator are defined as T& and const T& respectively.
   • If T is a reference type, reference and const_reference are ill-formed because reference to reference cannot be formed (reference collapsing
   • If T is const-qualified, reference and const_reference are the same, and the overload set of address()