Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/memory/polymorphic allocator"

From cppreference.com
< cpp‎ | memory
(LWG3037, noting inline but not DR listing)
m (##)
 
(13 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
{{cpp/memory/pmr/title|polymorphic_allocator}}
 
{{cpp/memory/pmr/title|polymorphic_allocator}}
 
{{cpp/memory/polymorphic_allocator/navbar}}
 
{{cpp/memory/polymorphic_allocator/navbar}}
−
{{ddcl|header=memory_resource | since=c++17 |
+
{{dcl begin}}
 +
{{dcl header|memory_resource}}
 +
{{dcl rev multi
 +
|since1=c++17|dcl1=
 
template< class T >
 
template< class T >
 +
class polymorphic_allocator;
 +
|since2=c++20|dcl2=
 +
template< class T = std::byte >
 
class polymorphic_allocator;
 
class polymorphic_allocator;
 
}}
 
}}
 +
{{dcl end}}
  
−
The class template {{tt|std::pmr::polymorphic_allocator}} is an {{named req|Allocator}} whose allocation behavior depends on the memory resource it is constructed with. Thus, different instances of {{tt|polymorphic_allocator}} can exhibit entirely different allocation behavior. This runtime polymorphism allows objects using {{tt|polymorphic_allocator}} to behave as if they used different allocator types at run time despite the identical static allocator type.
+
The class template {{tt|std::pmr::polymorphic_allocator}} is an {{named req|Allocator}} which exhibits different allocation behavior depending upon the {{lc|std::pmr::memory_resource}} from which it is constructed. Since {{tt|memory_resource}} uses runtime polymorphism to manage allocations, different container instances with {{tt|polymorphic_allocator}} as their static allocator type are interoperable, but can behave as if they had different allocator types.
  
−
All specializations of {{tt|polymorphic_allocator}} meet the [[cpp/named_req/Allocator#Allocator completeness requirements|Allocator completeness requirements]].<!-- LWG 3037 -->
+
All specializations of {{tt|polymorphic_allocator}} meet the {{lsd|cpp/named req/Allocator#Allocator completeness requirements}}.<!-- LWG 3037 -->
  
−
=== Member types ===
+
The {{tt|polymorphic_allocator::construct}} member function does {{lsd|cpp/memory/uses allocator#Uses-allocator construction}}, so that the elements of a container using a {{tt|polymorphic_allocator}} will use that same allocator for their own allocations. For example, a {{c|std::pmr::vector<std::pmr::string>}} will use the same {{tt|memory_resource}} for the {{tt|vector}}'s storage and each {{tt|string}}'s storage.
 +
 
 +
For non-polymorphic allocators, similar propagation can be achieved with the help of {{lc|std::scoped_allocator_adaptor}}.
 +
 
 +
===Member types===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc hitem| Member type | definition}}
+
{{dsc hitem|Member type|definition}}
−
{{dsc |{{tt|value_type}} | {{tt|T}}}}
+
{{dsc|{{tt|value_type}}|{{tt|T}}}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Member functions===
 
===Member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc constructor}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc constructor}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc destructor}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc destructor}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc operator{{=}}}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc operator{{=}}}}
  
−
{{dsc h2 | Public member functions}}
+
{{dsc h2|Public member functions}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc allocate}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc allocate}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc deallocate}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc deallocate}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc construct}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc construct}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc destroy}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc destroy}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc select_on_container_copy_construction}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc allocate_bytes}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc resource}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc deallocate_bytes}}
 +
{{dsc inc|cpp/memory/polymorphic_allocator/dsc allocate_object}}
 +
{{dsc inc|cpp/memory/polymorphic_allocator/dsc deallocate_object}}
 +
{{dsc inc|cpp/memory/polymorphic_allocator/dsc new_object}}
 +
{{dsc inc|cpp/memory/polymorphic_allocator/dsc delete_object}}
 +
{{dsc inc|cpp/memory/polymorphic_allocator/dsc select_on_container_copy_construction}}
 +
{{dsc inc|cpp/memory/polymorphic_allocator/dsc resource}}
 
{{dsc end}}
 
{{dsc end}}
  
−
=== Non-member functions ===
+
===Non-member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/memory/polymorphic_allocator/dsc operator eq}}
+
{{dsc inc|cpp/memory/polymorphic_allocator/dsc operator eq}}
 
{{dsc end}}
 
{{dsc end}}
  
−
=== Notes ===
+
===Notes===
 
{{tt|polymorphic_allocator}} does not propagate on container copy assignment, move assignment, or swap. As a result, move assignment of a {{tt|polymorphic_allocator}}-using container can throw, and swapping two {{tt|polymorphic_allocator}}-using containers whose allocators do not compare equal results in undefined behavior.
 
{{tt|polymorphic_allocator}} does not propagate on container copy assignment, move assignment, or swap. As a result, move assignment of a {{tt|polymorphic_allocator}}-using container can throw, and swapping two {{tt|polymorphic_allocator}}-using containers whose allocators do not compare equal results in undefined behavior.
 +
 +
{{feature test macro|__cpp_lib_polymorphic_allocator|{{tt|std::pmr::polymorphic_allocator<>}} as a vocabulary type|value=201902L|std=C++20}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/memory/dsc memory_resource}}
+
{{dsc inc|cpp/memory/dsc memory_resource}}
 
{{dsc end}}
 
{{dsc end}}
  
−
{{langlinks|ja|zh}}
+
{{langlinks|es|ja|ru|zh}}

Latest revision as of 08:18, 25 October 2023

 
C++
 
Dynamic memory management
Uninitialized memory algorithms
Constrained uninitialized memory algorithms
Allocators
Garbage collection support
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)



 
std::pmr::polymorphic_allocator
 
Defined in header <memory_resource>
template< class T >
class polymorphic_allocator;
 (since C++17)
(until C++20)
template< class T = std::byte >
class polymorphic_allocator;
 (since C++20)

The class template std::pmr::polymorphic_allocator is an Allocator which exhibits different allocation behavior depending upon the std::pmr::memory_resource from which it is constructed. Since memory_resource uses runtime polymorphism to manage allocations, different container instances with polymorphic_allocator as their static allocator type are interoperable, but can behave as if they had different allocator types.

All specializations of polymorphic_allocator meet the allocator completeness requirements.

The polymorphic_allocator::construct member function does uses-allocator construction, so that the elements of a container using a polymorphic_allocator will use that same allocator for their own allocations. For example, a std::pmr::vector<std::pmr::string> will use the same memory_resource for the vector's storage and each string's storage.

For non-polymorphic allocators, similar propagation can be achieved with the help of std::scoped_allocator_adaptor.

Contents

[edit] Member types

Member type definition
value_type T

[edit] Member functions

 constructs a polymorphic_allocator
(public member function) [edit]
(destructor)
(implicitly declared)
 implicitly declared destructor
(public member function) [edit]
operator=
[deleted]
 copy assignment operator is deleted
(public member function) [edit]
Public member functions
allocate memory
(public member function) [edit]
deallocate memory
(public member function) [edit]
constructs an object in allocated storage
(public member function) [edit]
(deprecated in C++20)(undeprecated in C++26)
 destroys an object in allocated storage
(public member function) [edit]
(C++20)
 allocate raw aligned memory from the underlying resource
(public member function) [edit]
(C++20)
 free raw memory obtained from allocate_bytes
(public member function) [edit]
(C++20)
 allocates raw memory suitable for an object or an array
(public member function) [edit]
(C++20)
 frees raw memory obtained by allocate_object
(public member function) [edit]
(C++20)
 allocates and constructs an object
(public member function) [edit]
(C++20)
 destroys and deallocates an object
(public member function) [edit]
create a new polymorphic_allocator for use by a container's copy constructor
(public member function) [edit]
returns a pointer to the underlying memory resource
(public member function) [edit]

[edit] Non-member functions

(removed in C++20)
 compare two polymorphic_allocators
(function) [edit]

[edit] Notes

polymorphic_allocator does not propagate on container copy assignment, move assignment, or swap. As a result, move assignment of a polymorphic_allocator-using container can throw, and swapping two polymorphic_allocator-using containers whose allocators do not compare equal results in undefined behavior.

Feature-test macro Value Std Feature
__cpp_lib_polymorphic_allocator 201902L (C++20) std::pmr::polymorphic_allocator<> as a vocabulary type

[edit] See also

(C++17)
 an abstract interface for classes that encapsulate memory resources
(class) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/memory/polymorphic_allocator&oldid=161351"