Allocator-aware library wrappers for dynamic allocation

Contents

1. Revision history
2. Summary
3. Example use cases
4. Dynamic allocation wrappers
5. Unique pointers
6. Design questions
7. Acknowledgements
8. Proposed wording

Revision history

• P0211R0: Initial proposal, pre-Jacksonville 2016.
• D0211r1: make pointer in allocate_delete const; delete unnecessary null check from allocate_new; add some more design questions.
• P0211R1: Rename functions as requested by LEWG in Jacksonville 2016. Add conversions to allocation_deleter. Add formal wording.
• P0211R2: Remove const from a few places where it would not have been allowed. Use std::to_address (introduced by P0653R2). Add noexcept to allocation_deleter constructors. Allow rebinding. Wording tweaks.
• P0211R3 (this version): Discuss the absence of _default_init versions. Update Remarks to Constraints, and update section numbers.

Summary

Short form: We propose to add library functions that allow the systematic use of allocators as a customisation point for dynamic allocations. The new functions complete the following picture:

Long form: The standard library rarely uses new/delete directly, but instead allows customisation of dynamic allocation and object construction via allocators. Currently this customisation is only available for container elements and for shared_ptr (as well as for a few other types that require dynamically allocated memory), but not for the top-level objects themselves.

The proposal is to complete the library facilities for allocator-based customisation by providing a direct mechanism for creating and destroying a dynamically stored object through an allocator, as well as a new deleter type for unique_ptr to hold an allocator-managed unique pointee, together with the appropriate factory function.

Example use cases

• Consider an arena allocator. A vector may put its elements into the arena, but the vector itself cannot easily be placed in the same arena. The proposed std::allocate_unique<std::vector<T, ScopedArenaAlloc<T>>>(arena_alloc) allows this. (Here we assume the use of the usual alias idiom template <class T> using ScopedArenaAlloc = std::scoped_allocator_adaptor<ArenaAlloc<T>>;).
• Consider a shared memory allocator. As in the previous example, containers will put their elements in shared memory, but one process needs to create the container itself and place it in shared memory. This is now possible with auto p = std::allocator_new<std::vector<T, ScopedShmemAlloc<T>>>(shmem_alloc). The returned pointer is presumably an offset pointer, and its offset value needs to be communicated to the other participating processes. The last process to use the container calls allocator_delete(shmem_alloc, p).
• Allocator support is frequently requested on Stack Overflow.

Dynamic allocation wrappers

Allocation and object creation

Object destruction and Deallocation

Unique pointers

To allow std::unique_ptr to use custom allocators, we first need a deleter template that stores the allocator:

The factory function is:

The type T must not be an array type. The pathological case where the template argument of allocation_deleter<A> is equal (up to qualification) to allocation_deleter<A> has to be taken into account for the purpose of the constructor.

Design questions

Naming

The name for the deleter class: “allocation_deleter” or “allocation_delete”? (We had previously used “allocate_delete” for both the function and the class, but that would have been very confusing.)

Default initialization

In C++20, the creation functions make_unique, make_shared, and allocate_shared were augmented by make_unique_default_init, make_shared_default_init, and allocate_shared_default_init. Whereas the former (called with no arguments) value-initialize an object (e.g. ::new T()), the latter default-initialize instead (e.g. ::new T).

One might ask whether there should not also be analogous default-initializing versions of the allocation helpers that are proposed here. However, this is a false analogy, and the answer is no: The proposed allocation helpers are meant to be a symmetric pair of allocation/construction and destruction/deallocation. Note that allocator_delete and allocation_deleter::operator() both call the allocator’s destroy function, which therefore must be matched with initialization by construct. This in turn precludes any notion of default-initialization, which the allocator API does not allow.

By contrast, make_unique and make_shared and their default-initializing versions do not use allocators and can thus correctly call delete or delete[] regardless of how the initialization was performed, and allocate_shared/allocate_shared_default_init use different dynamic deleters so that the allocator is used for the former, and raw delete is used for the latter.

Acknowledgements

Many thanks to Daniel Krügler for a thorough review and invaluable corrections of the first version from 2016, to the members of LEWG who reviewed the draft and provided many valuable improvements in 2018, and to Alisdair Meredith for pointing out default-initialization.

Proposed wording

In [memory.syn, 20.10.2], add to the synopsis:

Insert a new subsection between 20.9.9 (allocator traits) and 20.9.10 (the default allocator):

Insert a new subsection 20.11.1.1.? after 20.11.1.1.3 (default_delete<T[]>):

Append a new paragraph to the end of subsection 20.11.1.4 (unique_ptr creation):