18 Language support library [language.support]

18.6 Dynamic memory management [support.dynamic]

18.6.1 Storage allocation and deallocation [new.delete]

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

void* operator new(std::size_t size);

Effects: The allocation function ([basic.stc.dynamic.allocation]) called by a new-expression ([expr.new]) to allocate size bytes of storage suitably aligned to represent any object of that size.

Replaceable: a C++ program may define a function with this function signature that displaces the default version 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 a replacement version of this function.

Default behavior:

  • Executes a loop: Within the loop, the function first attempts to allocate the requested storage. Whether the attempt involves a call to the Standard C library function malloc is unspecified.

  • 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.

  • Otherwise, the function calls the current new_handler function ([new.handler]). If the called function returns, the loop repeats.

  • The loop terminates when an attempt to allocate the requested storage is successful or when a called new_handler function does not return.

void* operator new(std::size_t size, const std::nothrow_t&) noexcept;

Effects: Same as above, except that it is 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 a function with this function signature that displaces the default version 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. This nothrow version of operator new returns a pointer obtained as if acquired from the (possibly replaced) ordinary version. This requirement is binding on a replacement version of this function.

Default behavior: Calls operator new(size). 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;

Effects: The deallocation function ([basic.stc.dynamic.deallocation]) called by a delete-expression to render the value of ptr invalid.

Replaceable: a C++ program may define a function with signature void operator delete(void* ptr) noexcept that displaces the default version defined by the C++ standard library. If this function (without size parameter) is defined, the program should also define void operator delete(void* ptr, std::size_t size) noexcept. If this function with size parameter is defined, the program shall also define the 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 ]

Requires: ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new(std::size_t) or operator new(std::size_t,const std::nothrow_t&) which has not been invalidated by an intervening call to operator delete(void*).

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

Requires: If present, the std::size_t size argument shall equal the size argument passed to the allocation function that returned ptr.

Required behavior: Calls to operator delete(void* ptr, std::size_t size) may be changed to calls to operator delete(void* ptr) 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 function operator delete(void* ptr, std::size_t size) calls operator delete(ptr). [ 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 calloc, malloc, or realloc, declared in <cstdlib>.

void operator delete(void* ptr, const std::nothrow_t&) noexcept; void operator delete(void* ptr, std::size_t size, const std::nothrow_t&) noexcept;

Effects: The deallocation function ([basic.stc.dynamic.deallocation]) 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 a function with signature void operator delete(void* ptr, const std::nothrow_t&) noexcept that displaces the default version defined by the C++ standard library. If this function (without size parameter) is defined, the program should also define void operator delete(void* ptr, std::size_t size, const std::nothrow_t&) noexcept. If this function with size parameter is defined, the program shall also define the 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 ]

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

Requires: If present, the std::size_t size argument must equal the size argument passed to the allocation function that returned ptr.

Required behavior: Calls to operator delete(void* ptr, std::size_t size, const std::nothrow_t&) may be changed to calls to operator delete(void* ptr, const std::nothrow_t&) without affecting memory allocation. [ Note: A conforming implementation is for operator delete(void* ptr, std::size_t size, const std::nothrow_t&) to simply call operator delete(void* ptr, const std::nothrow_t&).  — end note ]

Default behavior: operator delete(void* ptr, std::size_t size, const std::nothrow_t&) calls operator delete(ptr, std::nothrow), and operator delete(void* ptr, const std::nothrow_t&) calls operator delete(ptr).