function
<new>

operator delete

ordinary (1)
void operator delete (void* ptr) throw();
nothrow (2)
void operator delete (void* ptr, const std::nothrow_t& nothrow_constant) throw();
placement (3)
void operator delete (void* ptr, void* voidptr2) throw();
ordinary (1)
void operator delete (void* ptr) noexcept;
nothrow (2)
void operator delete (void* ptr, const std::nothrow_t& nothrow_constant) noexcept;
placement (3)
void operator delete (void* ptr, void* voidptr2) noexcept;
Deallocate storage space
Default deallocation functions (single-object form).

(1) ordinary delete
Deallocates the memory block pointed by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new and rendering that pointer location invalid.
(2) nothrow delete
Same as above (1).
Same as above (1).
The default definition calls the first version (1): ::operator delete(ptr).
(3) placement delete
Does nothing.

The default allocation and deallocation functions are special components of the standard library; They have the following unique properties:
  • Global: All three versions of operator delete are declared in the global namespace, not within the std namespace.
  • Implicit: The allocating versions ((1) and (2)) are implicitly declared in every translation unit of a C++ program, no matter whether header <new> is included or not.
  • Replaceable: The allocating versions ((1) and (2)) are also replaceable: A program may provide its own definition that replaces the one provided by default to produce the result described above, or can overload it for specific types.

The second and third versions cannot be implicitly called by a delete-expression (the delete operator always calls the first version of this function exactly once for each of its arguments). But these versions are called automatically by a new-expression if the object construction fails (e.g., if the constructor of an object throws while being constructed by a new-expression with nothrow, the matching operator delete function accepting a nothrow argument is called).

operator delete can be called explicitly as a regular function, but in C++, delete is an operator with a very specific behavior: An expression with the delete operator, first calls the appropriate destructor (for class types), and then calls function operator delete (i.e., this function) to release the storage.

Parameters

ptr
A pointer to the memory block to be released, type-casted to a void*.
If this is a null-pointer, the function does nothing.
Otherwise, this pointer value should have been returned by a previous call to operator new, and have not yet been released by a previous call to this function.
Otherwise, this pointer value should have been returned by a previous call to operator new, and have not yet been released by a previous call to this function.
If the implementation has strict pointer safety, this pointer shall also be a safely-derived pointer.
nothrow_constant
The constant nothrow. This parameter is ignored in the default definition.
nothrow_t is the type of constant nothrow.
voidptr2
A void pointer. The value is ignored in the default definition.

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
// operator delete example
#include <iostream>     // std::cout

struct MyClass {
  MyClass() {std::cout <<"MyClass constructed\n";}
  ~MyClass() {std::cout <<"MyClass destroyed\n";}
};

int main () {
  MyClass * pt = new (std::nothrow) MyClass;
  delete pt;    // implicitly calls ::operator delete(pt)

  return 0;
}


Output:

MyClass constructed
MyClass destroyed

Data races

Only the storage referenced by ptr is modified.
Calls to allocation and deallocation functions that reuse the same unit of storage shall occur in a single total order where each deallocation happens before the next allocation.
This shall also apply to the observable behavior of custom replacements for this function.

Exception safety

No-throw guarantee: this function never throws exceptions.

Notice that an invalid value of ptr causes undefined behavior.

See also

operator new
Allocate storage space (function )
operator delete[]
Deallocate storage space of array (function )

C++