operator delete, operator delete[]
Header: <new>
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.
# Declarations
replaceable usual deallocation functions
void operator delete ( void* ptr ) throw();
(until C++11)
void operator delete ( void* ptr ) noexcept;
(since C++11)
void operator delete[]( void* ptr ) throw();
(until C++11)
void operator delete[]( void* ptr ) noexcept;
(since C++11)
void operator delete ( void* ptr, std::align_val_t al ) noexcept;
(since C++17)
void operator delete[]( void* ptr, std::align_val_t al ) noexcept;
(since C++17)
void operator delete ( void* ptr, std::size_t sz ) noexcept;
(since C++14)
void operator delete[]( void* ptr, std::size_t sz ) noexcept;
(since C++14)
void operator delete ( void* ptr, std::size_t sz,
std::align_val_t al ) noexcept;
(since C++17)
void operator delete[]( void* ptr, std::size_t sz,
std::align_val_t al ) noexcept;
(since C++17)
replaceable placement deallocation functions
void operator delete ( void* ptr, const std::nothrow_t& tag ) throw();
(until C++11)
void operator delete ( void* ptr, const std::nothrow_t& tag ) noexcept;
(since C++11)
void operator delete[]( void* ptr, const std::nothrow_t& tag ) throw();
(until C++11)
void operator delete[]( void* ptr, const std::nothrow_t& tag ) noexcept;
(since C++11)
void operator delete ( void* ptr, std::align_val_t al,
const std::nothrow_t& tag ) noexcept;
(since C++17)
void operator delete[]( void* ptr, std::align_val_t al,
const std::nothrow_t& tag ) noexcept;
(since C++17)
non-allocating placement deallocation functions
void operator delete ( void* ptr, void* place ) throw();
(until C++11)
void operator delete ( void* ptr, void* place ) noexcept;
(since C++11)
void operator delete[]( void* ptr, void* place ) throw();
(until C++11)
void operator delete[]( void* ptr, void* place ) noexcept;
(since C++11)
user-defined placement deallocation functions
void operator delete ( void* ptr, args... );
void operator delete[]( void* ptr, args... );
class-specific usual deallocation functions
void T::operator delete ( void* ptr );
void T::operator delete[]( void* ptr );
void T::operator delete ( void* ptr, std::align_val_t al );
(since C++17)
void T::operator delete[]( void* ptr, std::align_val_t al );
(since C++17)
void T::operator delete ( void* ptr, std::size_t sz );
void T::operator delete[]( void* ptr, std::size_t sz );
void T::operator delete ( void* ptr, std::size_t sz, std::align_val_t al );
(since C++17)
void T::operator delete[]( void* ptr, std::size_t sz, std::align_val_t al );
(since C++17)
class-specific placement deallocation functions
void T::operator delete ( void* ptr, args... );
void T::operator delete[]( void* ptr, args... );
class-specific usual destroying deallocation functions
void T::operator delete( T* ptr, std::destroying_delete_t );
(since C++20)
void T::operator delete( T* ptr, std::destroying_delete_t,
std::align_val_t al );
(since C++20)
void T::operator delete( T* ptr, std::destroying_delete_t, std::size_t sz );
(since C++20)
void T::operator delete( T* ptr, std::destroying_delete_t,
std::size_t sz, std::align_val_t al );
(since C++20)
# Parameters
ptr: pointer to a memory block to deallocate or a null pointersz: the size that was passed to the matching allocation functionplace: pointer used as the placement parameter in the matching placement newtag: overload disambiguation tag matching the tag used by non-throwing operator newal: alignment of the object or array element that was allocatedargs: arbitrary parameters matching a placement allocation function (may include std::size_t and std::align_val_t)
# Return value
(none)
# Notes
The call to the class-specific T::operator delete on a polymorphic class is the only case where a static member function is called through dynamic dispatch.
If the behavior of a deallocation function does not satisfy the default constraints, the behavior is undefined.
The following functions are required to be thread-safe:
Calls to these functions that allocate or deallocate a particular unit of storage occur in a single total order, and each such deallocation call happens-before the next allocation (if any) in this order.
# Defect reports
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| CWG 220 | C++98 | user-defined deallocation functions were permitted to throw | throwing from a deallocation functionresults in undefined behavior |
| CWG 1438 | C++98 | any use of an invalid pointer value was undefined behavior | only indirection and deallocation are |
| LWG 206 | C++98 | replacing (2) did not affect the default behavior of (10) | the default behavior changes accordingly |
| LWG 298 | C++98 | replacing (1) did not affect the default behavior of (9) | the default behavior changes accordingly |
| LWG 404 | C++98 | replacements of the replaceable deallocationfunctions could be declared inline | prohibited, no diagnostic required |
| LWG 2458 | C++14 | overloads taking (void*, std::size_t, conststd::nothrow_t&) were specified, but could never be called | removed spurious overloads |