Namespaces
Variants
Views
Actions

C++ concepts: Allocator

From cppreference.com
< cpp‎ | concept
Revision as of 19:35, 31 May 2013 by P12bot (Talk | contribs)

Encapsulates a memory allocation and deallocation strategy.

Every standard library component that may need to allocate or release storage, from std::string, std::vector, and every container except std::array, to std::shared_ptr and std::function, does so through an Allocator: an object of a class type that satisfies the following requirements.

Some requirements are optional: the template std::allocator_traits supplies the default implementations for all optional requirements, and all standard library containers and other allocator-aware classes access the allocator through std::allocator_traits, not directly.

Requirements

Given

  • A, an Allocator for type T
  • B, the same Allocator for type U
  • ptr, a value of type allocator_traits<A>::pointer, obtained by calling allocator_traits<A>::allocate()
  • cptr, a value of type allocator_traits<A>::const_pointer, obtained by conversion from ptr
  • vptr, a value of type allocator_traits<A>::void_pointer, obtained by conversion from ptr
  • cvptr, a value of type allocator_traits<A>::const_void_pointer, obtained by conversion from cptr or from vptr
  • xptr, a dereferencable pointer to some type X
Expression Requirements Return type
A::pointer (optional) Satisfies NullablePointer and RandomAccessIterator
A::const_pointer (optional) A::pointer is convertible to A::const_pointer. Satisfies NullablePointer and RandomAccessIterator
A::void_pointer (optional) A::pointer is convertible to A::void_pointer

B::void_pointer and A::void_pointer are the same type. Satisfies NullablePointer

A::const_void_pointer (optional) A::pointer, A::const_pointer, and A::void_pointer are convertible to A::const_void_pointer

B::const_void_pointer and A::const_void_pointer are the same type. Satisfies NullablePointer

A::value_type the type T
A::size_type (optional) A::size_type can represent the size of the largest object A can allocate unsigned integer type
A::difference_type (optional) A::difference_type can represent the difference of any two pointers to the objects allocated by A signed integer type
A::template rebind<U>::other (optional[1]) for any U, B::template rebind<T>::other is A the type B
*ptr T&
*cptr *cptr and *ptr identify the same object const T&
ptr->m same as (*ptr).m, if (*ptr).m is well-defined the type of T::m
cptr->m same as (*cptr).m, if (*cptr).m is well-defined the type of T::m
static_cast<A::pointer>(vptr) static_cast<A::pointer>(vptr) == ptr A::pointer
static_cast<A::const_pointer>(cvptr) static_cast<A::const_pointer>(vptr) == cptr A::const_pointer
a.allocate(n) allocates storage suitable for n objects of type T, but does not construct them. May throw exceptions. A::pointer
a.allocate(n, cptr) (optional) same as a.allocate(n), but may use cptr in unspecified manner to aid locality A::pointer
a.deallocate(ptr, n) deallocates storage previously allocated by a call to a.allocate(n). Does not call destructors, if any objects were constructed, they must be destroyed before calling a.deallocate(). Does not throw exceptions. (not used)
a.max_size() (optional) the largest value that can be passed to A::allocate() A::size_type
a1 == a2 returns true only if the storage allocated by the allocator a1 can be deallocated through a2. Establishes reflexive, symmetric, and transitive relationship. Does not throw exceptions. bool
a1 != a2 same as !(a1==a2) bool
A a1(a) Copy-constructs a1 such that a1 == a. Does not throw exceptions.
A a(b) Constructs a such that B(a)==b and A(b)==a. Does not throw exceptions.
A a1(std::move(a)) Constructs a1 such that it equals the prior value of a. Does not throw exceptions.
A a(std::move(b)) Constructs a such that it equals the prior value of A(b). Does not throw exceptions.
a.construct(xptr, args) (optional) Constructs an object of type X in previously-allocated storage at the address pointed to by xptr, using args as the constructor arguments
a.destroy(xptr) (optional) Destructs an object of type X pointed to by xptr, but does not deallocate any storage.
a.select_on_container_copy_construction() (optional) Provides an instance of A to be used by the container that is copy-constructed from the one that uses a currently. Usually returns either a copy of a or a default-constructed A(). A
a.propagate_on_container_copy_assignment (optional) true if the allocator of type A needs to be copied when the container that uses it is copy-assigned std::true_type or std::false_type or derived from such
a.propagate_on_container_move_assignment (optional) true if the allocator of type A needs to be copied when the container that uses it is move-assigned std::true_type or std::false_type or derived from such
a.propagate_on_container_swap (optional) true if the allocators of type A need to be swapped when two containers that use them are swapped std::true_type or std::false_type or derived from such

Notes: [1] rebind is only optional (provided by std::allocator_traits) if this allocator is a template of the form SomeAllocator<T, Args>, where Args is zero or more additional template parameters.