cpp/memory/new/operator delete

Deallocates storage previously allocated by a matching operator new. These deallocation functions are called by delete-expressions and by new-expressions to deallocate memory after destructing (or failing to construct) objects with dynamic storage duration. They may also be called using regular function call syntax.

@1@ Called by delete-expressions to deallocate storage previously allocated for a single object. The behavior of the standard library implementation of this function is undefined unless is a null pointer or is a pointer previously obtained from the standard library implementation of  or. @2@ Called by delete[]-expressions to deallocate storage previously allocated for an array of objects. The behavior of the standard library implementation of this function is undefined unless is a null pointer or is a pointer previously obtained from the standard library implementation of  or. @3,4@ Same as, except called if the alignment requirement exceeds. @5-6@ Called instead of if a user-defined replacement is provided, except that it's unspecified whether  or  is called when deleting objects of incomplete type and arrays of non-class and trivially-destructible class types. A memory allocator can use the given size to be more efficient. The standard library implementations are identical to. @7-8@ Same as, except called if the alignment requirement exceeds.

@9@ Called by the non-throwing single-object new-expressions if a constructor of the object throws an exception. The standard library implementation behaves the same as. @10@ Called by the non-throwing array new[]-expressions if a constructor of any object throws an exception (after executing the destructors of all objects in the array that were successfully constructed). The standard library implementation behaves the same as. @11,12@ Same as, except called if the alignment requirement exceeds.

@13@ Called by the standard single-object placement new expression if the object's constructor throws an exception. The standard library implementation of this function does nothing. @14@ Called by the standard array form of the placement new[] expression if any of the objects' constructors throws an exception (after executing the destructors of all objects that were constructed successfully). The standard library implementation of this function does nothing.

@15@ If defined, called by the custom single-object placement new expression with the matching signature if the object's constructor throws an exception. If a class-specific version is defined, it is called in preference to. If neither nor  is provided by the user, no deallocation function is called. @16@ If defined, called by the custom array form of placement new[] expression with the matching signature if any of the objects' constructors throws an exception (after executing the destructors for all objects that were constructed successfully). If a class-specific version is defined, it is called in preference to. If neither nor  is provided by the user, no deallocation function is called.

@17@ If defined, called by the usual single-object delete-expressions if deallocating an object of type. @18@ If defined, called by the usual array delete[]-expressions if deallocating an array of objects of type. @19,20@ If defined, called in preference to if the alignment requirement exceeds.

@21@ If defined, and if is not defined, called by the usual single-object delete-expressions if deallocating an object of type. @22@ If defined, and if is not defined, called by the usual array delete[]-expressions if deallocating an array of objects of type. @23,24@ If defined, and if are not defined, called in preference to allocator-unaware members if the alignment requirement exceeds.

@25@ If defined, called by the custom single-object placement new expression with the matching signature if the object's constructor throws an exception. If this function is not provided, and a matching is not provided either, no deallocation function is called. @26@ If defined, called by the custom array form of placement new[] expression with the matching signature if any of the objects' constructors throws an exception (after executing the destructors for all objects that were constructed successfully). If this function is not provided, and a matching is not provided either, no deallocation function is called.

@27-30@ If defined, delete-expressions does not execute the destructor for before placing a call to. Instead, direct invocation of the destructor such as by becomes the responsibility of this user-defined operator delete.

In all cases, if is a null pointer, the standard library deallocation functions do nothing. If the pointer passed to the standard library deallocation function was not obtained from the corresponding standard library allocation function, the behavior is undefined.

After the standard library deallocation function returns, all pointers referring to any part of the deallocated storage become invalid.

Indirection through a pointer that became invalid in this manner and passing it to a deallocation function (double-delete) is undefined behavior. Any other use is implementation-defined.

Return value
(none)

Exceptions
If a deallocation function terminates by throwing an exception, the behavior is undefined.

Global replacements
The replaceable deallocation functions are implicitly declared in each translation unit even if the  header is not included. These functions are replaceable: a user-provided non-member function with the same signature defined anywhere in the program, in any source file, replaces the corresponding implicit version for the entire program. Its declaration does not need to be visible.

The program is ill-formed, no diagnostic required if more than one replacement is provided in the program or if a replacement is declared with the specifier. The program is ill-formed if a replacement is defined in namespace other than global namespace, or if it is defined as a static non-member function at global scope.

The standard library implementations of the nothrow versions directly call the corresponding throwing versions. The standard library implementations of the size-aware deallocation functions directly call the corresponding size-unaware deallocation functions. The standard library implementations of size-unaware throwing array forms directly calls the corresponding single-object forms. Thus, replacing the throwing single object deallocation functions is sufficient to handle all deallocations.

Overloads of and  with additional user-defined parameters ("placement forms", ) may be declared at global scope as usual, and are called by the matching placement forms of new-expressions if a constructor of the object that is being allocated throws an exception.

The standard library placement forms of  cannot be replaced and can only be customized if the placement new-expression did not use the  syntax, by providing a class-specific placement delete  with matching signature:  or.

Class-specific overloads
Deallocation functions may be defined as static member functions of a class. These deallocation functions, if provided, are called by delete-expressions when deleting objects and arrays  of this class, unless the delete expression used the form  which bypasses class-scope lookup. The keyword is optional for these function declarations: whether the keyword is used or not, the deallocation function is always a static member function.

The delete expression looks for appropriate deallocation function's name starting from the class scope (array form looks in the scope of the array element class) and proceeds to the global scope if no members are found as usual. Note, that as per name lookup rules, any deallocation functions declared in class scope hides all global deallocation functions.

If the static type of the object that is being deleted differs from its dynamic type (such as when deleting a polymorphic object through a pointer to base), and if the destructor in the static type is virtual, the single object form of delete begins lookup of the deallocation function's name starting from the point of definition of the final overrider of its virtual destructor. Regardless of which deallocation function would be executed at run time, the statically visible version of operator delete must be accessible in order to compile. In other cases, when deleting an array through a pointer to base, or when deleting through pointer to base with non-virtual destructor, the behavior is undefined.

If the single-argument overload is not provided, but the size-aware overload taking std as the second parameter  is provided, the size-aware form is called for normal deallocation, and the C++ runtime passes the size of the object to be deallocated as the second argument. If both forms are defined, the size-unaware version is called.

Overloads of and  with additional user-defined parameters ("placement forms", ) may also be defined as class members. When the failed placement new expression looks for the corresponding placement delete function to call, it begins lookup at class scope before examining the global scope, and looks for the function with the signature matching the placement new:

If class-level is a template function, it must have the return type of, the first argument , and it must have two or more parameters. In other words, only placement forms can be templates. A template instance is never a usual deallocation function, regardless of its signature. The specialization of the template operator delete is chosen with template argument deduction.