Destructors

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

C++ language

General topics
Preprocessor Comments Keywords	ASCII chart Escape sequences History of C++
Flow control
Conditional execution statements
if statement	switch statement
Iteration statements
for loop range-for loop (C++11)	while loop do-while loop
Jump statements
continue statement break statement	goto statement return statement
Functions
function declaration
lambda function declaration
function template
inline specifier
exception specifications (deprecated)
noexcept specifier (C++11)
Exceptions
throw expression	try-catch block
Namespaces
namespace declaration	namespace aliases
Types
fundamental types compound types enumeration types	union types function types
decltype specifier (C++11)
Specifiers
cv specifiers
storage duration specifiers
constexpr specifier (C++11)
auto specifier (C++11)
alignas specifier (C++11)
Initialization
default initialization value initialization zero initialization copy initialization direct initialization	aggregate initialization list initialization (C++11) constant initialization reference initialization

Literals
integer literals character literals floating-point literals string literals	boolean literals nullptr (C++11) user-defined (C++11)
Expressions
value categories order of evaluation	operators operator precedence
alternative representations
Utilities
Types
typedef declaration
type alias declaration (C++11)
attributes (C++11)
Casts
implicit conversions
const_cast conversion
static_cast conversion
dynamic_cast conversion
reinterpret_cast conversion
C-style and functional cast
Memory allocation
new expression	delete expression
Classes
class declaration this pointer access specifiers	friend specifier initializer lists
Class-specific function properties
virtual function override specifier (C++11) final specifier (C++11)	explicit (C++11) static
Special member functions
default constructor copy constructor move constructor (C++11)	copy assignment move assignment (C++11) destructor
Templates
class template
function template
template specialization
parameter packs (C++11)
Miscellaneous
Inline assembly

 

A destructor is a special member function that is called when the lifetime of an object ends. The purpose of the destructor is to free the resources that the object may have acquired during its lifetime.

Syntax

~class_name ();	(1)
virtual ~class_name ();	(2)
~class_name () = default;	(3)	(since C++11)
~class_name () = delete;	(4)	(since C++11)

Explanation

1. Typical declaration of a destructor
2. Virtual destructor is usually required in a base class
3. Forcing a destructor to be generated by the compiler
4. Disabling the implicit destructor

The destructor is called whenever an object's lifetime ends, which includes

• program termination, for objects with static storage duration
• thread exit, for objects with thread-local storage duration (since C++11)
• end of scope, for objects with automatic storage duration and for temporaries whose life was extended by binding to a reference
• delete-expression, for objects with dynamic storage duration
• end of the full expression, for nameless temporaries
• stack unwinding, for objects with automatic storage duration when an exception escapes their block, uncaught.

The destructor may also be called directly, e.g. to destroy an object that was constructed using placement-new or through an allocator member function such as std::allocator::destroy(), to destroy an object that was constructed through the allocator. Note that calling a destructor directly for an ordinary object, such as a local variable, invokes undefined behavior when the destructor is called again, at the end of scope.

Implicitly-declared destructor

If no user-defined destructor is provided for a class type (struct, class, or union), the compiler will always declare a destructor as an inline public member of its class.

Deleted implicitly-declared copy destructor

The implicitly-declared or defaulted destructor for class T is undefined (until C++11) / defined as deleted (since C++11) if any of the following is true:

• T has a non-static data member that cannot be destructed (has deleted or inaccessible destructor)
• T has direct or virtual base class that cannot be destructed (has deleted or inaccessible destructors)
• T is a union and has a variant member with non-trivial destructor (since C++11)
• The implicitly-declared destructor is virtual (because the base class has a virtual destructor) and the lookup for the deallocation function (operator delete() results in a call to ambiguous, deleted, or inaccessible function.

Trivial destructor

The implicitly-declared destructor for class T is trivial if all of the following is true:

• The destructor is not virtual (that is, the base class destructor is not virtual)
• All direct base classes have virtual destructors
• All non-static data members of class type (or array of class type) have virtual destructors

A trivial destructor is a destructor that performs no action. Objects with trivial destructors don't require a delete-expression and may be disposed of by simply deallocating their storage. All data types compatible with the C language (POD types) are trivially destructible.

Implicitly-defined destructor

If the implicitly-declared destructor is not deleted or trivial, it is defined (that is, a function body is generated and compiled) by the compiler. This implicitly-defined destructor has an empty body.

Destruction sequence

For both user-defined or implicitly-defined destructors, after the body of the destructor is executed, the compiler calls the destructors for all non-static non-variant members of the class, in reverse order of declaration, then it calls the destructors of all direct base classes in reverse order of construction (which in turn call the destructors of their members and their base classes, etc), and then, if this object is of most-derived class, it calls the destructors of all virtual bases.

Even when the destructor is called directly (e.g. obj.~Foo();), the return statement in ~Foo() does not return control to the caller immediately: it calls all those member and base destructors first.

Virtual destructors

Deleting an object through pointer to base invokes undefined behavior unless the destructor in the base class is virtual:

class Base {
 public:
    virtual ~Base() {}
};
class Derived : public Base {};
Base* b = new Derived;
delete b; // safe

A common guideline is that a destructor for a base class must be either public and virtual or protected and nonvirtual

Pure virtual destructors

A destructor may be declared pure virtual, for example in a base class which needs to be made abstract, but has no other suitable functions that could be declared pure virtual. Such destructor must have a definition, since all base class destructors are always called when the derived class is destroyed:

class AbstractBase {
 public:
    virtual ~AbstractBase() = 0;
};
AbstractBase::~AbstractBase() {}
class Derived : public AbstractBase {};
// AbstractBase obj;   // compiler error
Derived obj;           // OK

Example

run this code

#include <iostream>
 
struct A
{
    int i;
 
    A ( int i ) : i ( i ) {}
 
    ~A()
    {
        std::cout << "~a" << i << std::endl;
    }
};
 
int main()
{
    A a1(1);
    A* p;
 
    { // nested scope
        A a2(2);
        p = new A(3);
    } // a2 out of scope
 
    delete p; // calls the destructor of a3
}

Output:

~a2
~a3
~a1