operator delete, operator delete[]

Deallocates storage previously allocated by a matching operator new. These deallocation functions are called by delete-expressions and by new-expressions

In all cases, if ptr

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.

Parameters

Return value

(none)

Exceptions

If a deallocation function terminates by throwing an exception, the behavior is undefined , even if it is declared with noexcept(false) (since C++11)

Global replacements

The replaceable deallocation functions (1-12) are implicitly declared in each translation unit even if the <new> header is not included. These functions are replaceable

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 inline

The standard library implementations of the nothrow versions (9,10) directly call the corresponding throwing versions (1,2). The standard library implementations of the size-aware deallocation functions (5-8) directly call the corresponding size-unaware deallocation functions (1-4). The standard library implementations of size-unaware throwing array forms (2,4) directly calls the corresponding single-object forms (1,3). Thus, replacing the throwing single object deallocation functions (1,3)

#include <cstdio>
#include <cstdlib>
#include <new>
 
// no inline, required by [replacement.functions]/3
void* operator new(std::size_t sz)
{
    std::printf("1) new(size_t), size = %zu\n", sz);
    if (sz == 0)
        ++sz; // avoid std::malloc(0) which may return nullptr on success
 
    if (void *ptr = std::malloc(sz))
        return ptr;
 
    throw std::bad_alloc{}; // required by [new.delete.single]/3
}
 
// no inline, required by [replacement.functions]/3
void* operator new[](std::size_t sz)
{
    std::printf("2) new[](size_t), size = %zu\n", sz);
    if (sz == 0)
        ++sz; // avoid std::malloc(0) which may return nullptr on success
 
    if (void *ptr = std::malloc(sz))
        return ptr;
 
    throw std::bad_alloc{}; // required by [new.delete.single]/3
}
 
void operator delete(void* ptr) noexcept
{
    std::puts("3) delete(void*)");
    std::free(ptr);
}
 
void operator delete(void* ptr, std::size_t size) noexcept
{
    std::printf("4) delete(void*, size_t), size = %zu\n", size);
    std::free(ptr);
}
 
void operator delete[](void* ptr) noexcept
{
    std::puts("5) delete[](void* ptr)");
    std::free(ptr);
}
 
void operator delete[](void* ptr, std::size_t size) noexcept
{
    std::printf("6) delete[](void*, size_t), size = %zu\n", size);
    std::free(ptr);
}
 
int main()
{
    int* p1 = new int;
    delete p1;
 
    int* p2 = new int[10]; // guaranteed to call the replacement in C++11
    delete[] p2;
}

// Compiled with GCC-5 in C++17 mode to obtain the following:
1) op new(size_t), size = 4
4) op delete(void*, size_t), size = 4
2) op new[](size_t), size = 40
5) op delete[](void* ptr)

Overloads of operator delete and operator delete[] with additional user-defined parameters ("placement forms", (15,16)) may be declared at global scope as usual, and are called by the matching placement forms of new-expressions

The standard library placement forms of operator delete (13,14) cannot be replaced and can only be customized if the placement new-expression did not use the ::new syntax, by providing a class-specific placement delete (25,26) with matching signature: void T:: operator delete( void *, void * ) or void T:: operator delete[ ] ( void *, void * )

Class-specific overloads

Deallocation functions (17-24) may be defined as static member functions of a class. These deallocation functions, if provided, are called by delete-expressions when deleting objects (17,19,21) and arrays (18,20,22) of this class, unless the delete expression used the form ::delete which bypasses class-scope lookup. The keyword static

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

If the static type of the object that is being deleted differs from its dynamic type (such as when deleting a polymorphic

If the single-argument overload (17,18) is not provided, but the size-aware overload taking std::size_t as the second parameter (21,22

#include <cstddef>
#include <iostream>
 
// sized class-specific deallocation functions
struct X
{
    static void operator delete(void* ptr, std::size_t sz)
    {
        std::cout << "custom delete for size " << sz << '\n';
        ::operator delete(ptr);
    }
 
    static void operator delete[](void* ptr, std::size_t sz)
    {
        std::cout << "custom delete for size " << sz << '\n';
        ::operator delete[](ptr);
    }
};
 
int main()
{
    X* p1 = new X;
    delete p1;
 
    X* p2 = new X[10];
    delete[] p2;
}

custom delete for size 1
custom delete for size 18

Overloads of operator delete and operator delete[] with additional user-defined parameters ("placement forms", (25,26

#include <cstddef>
#include <iostream>
#include <stdexcept>
 
struct X
{
    X() { throw std::runtime_error("X(): std::runtime_error"); }
 
    // custom placement new
    static void* operator new(std::size_t sz, bool b)
    {
        std::cout << "custom placement new called, b = " << b << '\n';
        return ::operator new(sz);
    }
 
    // custom placement delete
    static void operator delete(void* ptr, bool b)
    {
        std::cout << "custom placement delete called, b = " << b << '\n';
        ::operator delete(ptr);
    }
};
 
int main()
{
    try
    {
        [[maybe_unused]] X* p1 = new (true) X;
    }
    catch (const std::exception& ex)
    {
        std::cout << ex.what() << '\n';
    }
}

custom placement new called, b = 1
custom placement delete called, b = 1
X(): std::runtime_error

If class-level operator delete is a template function, it must have the return type of void, the first argument void * , 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

Notes

The call to the class-specific T::operator delete

If the behavior of a deallocation function does not satisfy the default constraints, the behavior is undefined.

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also