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

Every standard library component that may need to allocate or release storage, fromstd::string,std::vector, and every container, exceptstd::array(since C++11) andstd::inplace_vector(since C++26), tostd::shared_ptr andstd::function(until C++17), does so through anAllocator: an object of a class type that satisfies the following requirements.

The implementation of many allocator requirements is optional because allAllocatorAwareContainer access allocators indirectly throughstd::allocator_traits, andstd::allocator_traits supplies the default implementation of those requirements.

[edit]Requirements

Given

• T, anon-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, anAllocator type for typeT,
• a, an object of typeA,
• B, the correspondingAllocator type for some cv-unqualified object typeU (as obtained by rebindingA),
• b, an object of typeB,
• p, a value of typestd::allocator_traits<A>::pointer, obtained by callingstd::allocator_traits<A>::allocate(),
• cp, a value of typestd::allocator_traits<A>::const_pointer, obtained by conversion fromp,
• vp, a value of typestd::allocator_traits<A>::void_pointer, obtained by conversion fromp,
• cvp, a value of typestd::allocator_traits<A>::const_void_pointer, obtained by conversion fromcp or fromvp,
• xp, a dereferenceable pointer to some cv-unqualified object typeX,
• r, an lvalue of typeT obtained by the expression*p,
• n, a value of typestd::allocator_traits<A>::size_type.

Notes:

1. ↑See alsofancy pointers below.
2. ↑rebind is only optional (provided bystd::allocator_traits) if this allocator is a template of the formSomeAllocator<T, Args>, whereArgs is zero or more additional template type parameters.

Given

• x1 andx2, objects of (possibly different) typesX::void_pointer,X::const_void_pointer,X::pointer, orX::const_pointer

Then,x1 andx2 areequivalently-valued pointer values, if and only if bothx1 andx2 can be explicitly converted to the two corresponding objectspx1 andpx2 of typeX::const_pointer, using a sequence ofstatic_casts using only these four types, and the expressionpx1== px2 evaluates totrue.

Given

• w1 andw2, objects of typeX::void_pointer

Then, for the expressionw1== w2 andw1!= w2 either or both objects may be replaced by anequivalently-valued object of typeX::const_void_pointer with no change in semantics.

Given

• p1 andp2, objects of typeX::pointer

Then, for the expressionsp1== p2,p1!= p2,p1< p2,p1<= p2,p1>= p2,p1> p2,p1- p2 either or both objects may be replaced by anequivalently-valued object of typeX::const_pointer with no change in semantics.

The above requirements make it possible to compareContainer'siterators andconst_iterators.

[edit]Stateful and stateless allocators

EveryAllocator type is eitherstateful orstateless. Generally, a stateful allocator type can have unequal values which denote distinct memory resources, while a stateless allocator type denotes a single memory resource.

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

[edit]Fancy pointers

When the member typepointer is not a raw pointer type, it is commonly referred to as a"fancy pointer". Such pointers were introduced to support segmented memory architectures and are used today to access objects allocated in address spaces that differ from the homogeneous virtual address space that is accessed by raw pointers. An example of a fancy pointer is the mapping address-independent pointerboost::interprocess::offset_ptr, which makes it possible to allocate node-based data structures such asstd::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 templatestd::pointer_traits(since C++11).The functionstd::to_address can be used to obtain a raw pointer from a fancy pointer.(since C++20)

[edit]Standard library

The following standard library components satisfy theAllocator requirements:

[edit]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))throwstd::bad_array_new_length(); if(auto p=static_cast<T*>(std::malloc(n* sizeof(T)))){            report(p, n);return p;} throwstd::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>&){returntrue;} template<class T,class U>bool operator!=(const Mallocator<T>&,const Mallocator<U>&){returnfalse;} int main(){std::vector<int, Mallocator<int>> v(8);    v.push_back(42);}

Alloc: 32 bytes at 0x2020c20Alloc: 64 bytes at 0x2023c60Dealloc: 32 bytes at 0x2020c20Dealloc: 64 bytes at 0x2023c60

[edit]Defect reports

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

1. ↑The member typesreference andconst_reference ofstd::allocator are defined asT& andconst T& respectively.
   • IfT is a reference type,reference andconst_reference are ill-formed because reference to reference cannot be formed (reference collapsing was introduced in C++11).
   • IfT is const-qualified,reference andconst_reference are the same, and the overload set ofaddress() is ill-formed.

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文