17 Language support library [support]

17.6 Dynamic memory management [support.dynamic]

17.6.2 Storage allocation and deallocation [new.delete]

17.6.2.1 Single-object forms [new.delete.single]

[[nodiscard]] void* operator new(std::size_t size);
[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment);

Effects: The allocation functions called by a new-expression to allocate size bytes of storage.

The second form is called for a type with new-extended alignment, and the first form is called otherwise.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby displace the default versions defined by the C++ standard library.

Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), or else throw a bad_alloc exception.

This requirement is binding on any replacement versions of these functions.

Default behavior:

(4.1)
Executes a loop: Within the loop, the function first attempts to allocate the requested storage. Whether the attempt involves a call to the C standard library functions malloc or aligned_alloc is unspecified.
(4.2)
Returns a pointer to the allocated storage if the attempt is successful. Otherwise, if the current new_handler ([get.new.handler]) is a null pointer value, throws bad_alloc.
(4.3)
Otherwise, the function calls the current new_handler function. If the called function returns, the loop repeats.
(4.4)
The loop terminates when an attempt to allocate the requested storage is successful or when a called new_handler function does not return.

🔗

[[nodiscard]] void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment,
                                 const std::nothrow_t&) noexcept;

Effects: Same as above, except that these are called by a placement version of a new-expression when a C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby displace the default versions defined by the C++ standard library.

Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), or else return a null pointer.

Each of these nothrow versions of operator new returns a pointer obtained as if acquired from the (possibly replaced) corresponding non-placement function.

This requirement is binding on any replacement versions of these functions.

Default behavior: Calls operator new(size), or operator new(size, alignment), respectively.

If the call returns normally, returns the result of that call.

Otherwise, returns a null pointer.

[Example

T* p1 = new T;                  // throws bad_alloc if it fails
T* p2 = new(nothrow) T;         // returns nullptr if it fails

— end example

]

🔗

void operator delete(void* ptr) noexcept;
void operator delete(void* ptr, std::size_t size) noexcept;
void operator delete(void* ptr, std::align_val_t alignment) noexcept;
void operator delete(void* ptr, std::size_t size, std::align_val_t alignment) noexcept;

Effects: The deallocation functions called by a delete-expression to render the value of ptr invalid.

Replaceable: A C++ program may define functions with any of these function signatures, and thereby displace the default versions defined by the C++ standard library.

If a function without a size parameter is defined, the program should also define the corresponding function with a size parameter.

If a function with a size parameter is defined, the program shall also define the corresponding version without the size parameter.

[Note

The default behavior below may change in the future, which will require replacing both deallocation functions when replacing the allocation function.

— end note

]

Preconditions: ptr is a null pointer or its value represents the address of a block of memory allocated by an earlier call to a (possibly replaced) operator new(std::size_t) or operator new(std::size_t, std::align_val_t) which has not been invalidated by an intervening call to operator delete.

Preconditions: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr is a safely-derived pointer.

Preconditions: If the alignment parameter is not present, ptr was returned by an allocation function without an alignment parameter.

If present, the alignment argument is equal to the alignment argument passed to the allocation function that returned ptr.

If present, the size argument is equal to the size argument passed to the allocation function that returned ptr.

Required behavior: A call to an operator delete with a size parameter may be changed to a call to the corresponding operator delete without a size parameter, without affecting memory allocation.

[Note

A conforming implementation is for operator delete(void* ptr, std::size_t size) to simply call operator delete(ptr).

— end note

]

Default behavior: The functions that have a size parameter forward their other parameters to the corresponding function without a size parameter.

[Note

See the note in the above Replaceable: paragraph.

— end note

]

Default behavior: If ptr is null, does nothing.

Otherwise, reclaims the storage allocated by the earlier call to operator new.

Remarks: It is unspecified under what conditions part or all of such reclaimed storage will be allocated by subsequent calls to operator new or any of aligned_alloc, calloc, malloc, or realloc, declared in <cstdlib> ([cstdlib.syn]).

🔗

void operator delete(void* ptr, const std::nothrow_t&) noexcept;
void operator delete(void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;

Effects: The deallocation functions called by the implementation to render the value of ptr invalid when the constructor invoked from a nothrow placement version of the new-expression throws an exception.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby displace the default versions defined by the C++ standard library.

Preconditions: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr is a safely-derived pointer.

Preconditions: If the alignment parameter is not present, ptr was returned by an allocation function without an alignment parameter.

If present, the alignment argument is equal to the alignment argument passed to the allocation function that returned ptr.

Default behavior: Calls operator delete(ptr), or operator delete(ptr, alignment), respectively.